Version: 1.6.1

Webhook

TaxBandits now introduces adding multiple webhook Callback URLs to the same event type. Whenever a recipient completes the Form W-9 or W-8BEN, the webhook will be posted to the Callback URL the client prefers by giving its WebhookRef in the request payload. The support for multiple webhooks for the same event type could be a big help during development as well as in the production environment to act as a load balancer.

A maximum of 5 webhook Callback URLs can be added to the WhCertificate Status Change event type.

Go to Webhooks for information on Webhooks in TaxBandits.

How does it work?

Log in to the developer console.
- Sandbox Console URL: sandbox.taxbandits.com
- Live Console URL: console.taxbandits.com
Then navigate to Settings >> Webhooks.
To add the multiple webhook Callback URLs inside the console site. Click on the Add Webhook button.

Webhook Settings

On the Add Webhook pop-up, choose the Event Type as WhCertificate Status Change. Once you select the event type, you will have the option to add up to 5 webhook Callback URLs.

WHCertificate Popup

On Save, TaxBandits generates a unique Webhook Reference (GUID) against each Callback URL. Store these Webhook References at your end and pass them in the request JSON for us to post the webhook response to the corresponding Callback URL. If you don't pass one, the webhook response will be posted to the default Callback URL (Callback URL 1).

WHCertificate Reference

WHCertificate CallBackUrls

When you call the WhCertificate/RequestByUrl endpoint, you can mention the preferred Callback URL by sending the stored Webhook Reference to the node WebhookRef. The WebhookRef node is optional.

When a recipient completes the W-9/W-8BEN, the webhook will be posted to the Callback URL that is tied to the WebhookRef given in the request.

If you do not specify the WebhookRef in the request, then the webhook will be posted to the default Callback URL.

Request JSON with WebhookRef

Sample Json

Response Body

Field	Type	Description
FormType	String	Type of Form (W-9 or W-8BEN).
WebhookRef	Guid	Unique identifier of the webhook. TaxBandits generates a unique Webhook Reference (GUID) against each Callback URL when adding it in the console site. If you pass the WebhookRef in the request JSON, we will post the webhook response to the corresponding Callback URL. If you don't pass one, the webhook response will be posted to the default Callback URL.
FormW9	Object	Contains Form W-9 Information.
SubmissionId	Guid	Unique identifier of a submission.
Requester	Object	Requester information.
BusinessId	Guid	A unique identifier of the business.
BusinessNm	String	Requester Name. If the requester is a Business, then the Business Name will be returned. If the requester is an Individual, then the Payer’s full name will be returned.
TINType	String	TIN Type of the Requester.
TIN	String	Taxpayer Identification Number of the requester.
PayeeRef	String	Unique identifier of the recipient
RecipientId	Guid	An unique ID generated by TaxBandits after the return is created and will be returned in the Response. You can use this id for your future reference to update.
W9Status	String	Status of the W-9
StatusTs	String	Timestamp of the W-9 Status
TINMatching	Object	TIN Matching information.
Status	String	TIN Matching status.
StatusTs	String	Timestamp of the TIN Matching Status.
Errors	String	Shows the detailed error message.
FormW9RequestType	String	Form W-9 requested Type. COMMON_URL_API - Form W-9 was requested using the API method RequestByUrl.
PdfUrl	String	URL to download the completed W-9
Email	String	Email Address of the recipient. This is the email to which the W-9 request was sent. The value will be null if the Form W-9 was requested using the API method RequestByURL
FormData	Object	Form W-9 data of the recipient
Line1Nm	string	Name as shown on the income tax return
Line2Nm	string	Business name/disregarded entity name, if different from Line1 Name
TINType	string	TIN type of the recipient. Either EIN or SSN
TIN	string	Recipient’s TIN
Address	Object	Recipient’s complete address
Address1	string	Recipient’s Address 1 (number, street)
Address2	string	Recipient’s Address 2 (apt. or suite no.)
City	string	Recipient’s City
State	string	Recipient’s State
ZipCd	string	Recipient’s Zip Code
FederalTaxClassification	string	U.S. Federal Tax Classification of the person whose name is entered on Line 1
ExemptPayeeCd	string	This code identifies the recipient is exempt from backup withholding
ExemptFromFATCA	string	This code identifies recipients that are exempt from reporting under FATCA.
IsBackUpWH	Boolean	When true, identifies the recipient is subject to backup withholding. The completed Form W-9 PDF will have the item 2 under Part II crossed out. When false, identifies the recipient is not subject to backup withholding.
Errors	Object	Shows detailed error information.
FormW8Ben	Object	Form W-8BEN Information.
SubmissionId	Guid	Unique identifier of a submission.
Requester	Object	Requester information.
BusinessId	Guid	A unique identifier of the business.
BusinessNm	String	Business Name of the requester. If the requester is an Individual, then the Payer’s full name will be returned.
TINType	String	TIN Type of the Requester.
TIN	String	Taxpayer Identification Number of the requester.
PayeeRef	String	Unique identifier of the recipient
W8BENStatus	String	Status of the W-8BEN.
StatusTs	String	Timestamp of the W-8BEN Status.
FormW8BENRequestType	String	Form W-8BEN requested Type. COMMON_URL_API - Form W-8BEN was requested using the API method RequestByUrl.
PdfUrl	String	URL to download the completed W-8BEN.
Email	String	Email Address of the recipient. This is the email to which the W-8BEN request was sent.The value will be null if the Form W-8BEN was requested using the API method RequestByURL.
FormData	Object	Form W-8BEN data of the recipient.
NmOfIndividual	string	Name of the Foreign Individual.
CitizenOfCountry	string	Recipient country of citizenship.
USTINType	string	TIN type of the recipient. Either SSN or ITIN.
USTIN	string	Recipient’s TIN
ForeignTIN	string	Foreign TIN of the recipient.
DOB	string	Date of Birth of the recipient
PermanentAddress	Object	Recipient’s permanent address.
Address	string	Recipient’s Address.
City	string	Recipient’s City
State	string	Recipient’s State
Country	string	Recipient’s Country
PostalCd	string	Recipient’s Zip Code
MailingAddress	Object	Recipient’s mailing address.
Address	string	Recipient’s Address.
City	string	Recipient’s City
State	string	Recipient’s State
Country	string	Recipient’s Country
PostalCd	string	Recipient’s Zip Code
TaxTreatyBenefits	Object	Tax Treaty Benefits.
BeneficiaryCountry	string	Country where the recipient claim to be a resident for income tax treaty purposes.
ClaimingProvArticlePara	string	Article and paragraph of the treaty benefits.
RateOfWH	string	Rate of Withholding.
TypeOfIncome	string	Type of income for which recipient claiming the treaty benefits.
AdditionalConditions	string	Additional conditions from the tax treaty benefits.
Signature	Object	Signature of the recipient.
SignerNm	string	Name of the signer.
CapacityInWhichActing	string	If the form is signed by an agent on the individual’s behalf, enter the capacity in which they are acting.
Errors	Object	Shows detailed error information. Sample Webhook Response for W8Ben :

Scenario 1: The recipient has completed Form W-8BEN.

{
 "FormType": "W8Ben",
 "WebhookRef": "7a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",
 "FormW9": null,
 "FormW8Ben": {
   "SubmissionId": "4a36dc14-f059-4c89-83cd-ff9e350ed0a0",
   "Requester": {
     "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
     "PayerRef": null,
     "BusinessNm": "John Enterprises",
     "TINType": "EIN",
     "TIN": "22-2222222"
   },
   "PayeeRef": "7484391234545",
   "W8BENStatus": "COMPLETED",
   "StatusTs": "2021-02-19 14:36:28 -05:00",
   "FormW8BENRequestType": "URL_API",
   "PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
   "Email": "steve@abcinc.com",
   "FormData": {
     "NmOfIndividual": "Joseph Smith",
     "CitizenOfCountry": "Canada",
     "USTINType": "SSN",
     "USTIN": "111-11-1111",
     "ForeignTIN": null,
     "DOB": "07/08/1990",
     "PermanentAddress": {
       "Address": "123 E. Main St",
       "City": "Rock Hill",
       "State": "SC",
       "Country": "USA",
       "ZipCd": "29730"
     },
     "MailingAddress": {
       "Address": null,
       "City": null,
       "State": null,
       "Country": null,
       "ZipCd": null
     },
     "TaxTreatyBenefits": {
       "BeneficiaryCountry": "Canada",
       "ClaimingProvArticlePara": "VII",
       "RateOfWH": "27.50",
       "TypeOfIncome": "Royalties",
       "AdditionalConditions": null
     },
     "Signature": {
       "SignerNm": "Joseph",
       "CapacityInWhichActing": "Guardian"
     }
   },
   "Errors": null
 },
 "Errors": null
}

Scenario 2: The recipient has completed Form W-9 and TIN Matching is Inprogress.

{
 "FormType": "FormW9",
 "WebhookRef": "7a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",
 "FormW9": {
   "SubmissionId": "b870040d-fded-420b-b424-28bf0dd11261",
   "Requester": {
     "BusinessId": "fb6ddd28-ad30-4fc2-bd17-38a937f2aa81",
     "PayerRef": null,
     "BusinessNm": "John Enterprises",
     "TINType": "EIN",
     "TIN": "XX-XXX2222"
   },
   "PayeeRef": "Pe123451234",
   "RecipientId": "sdf3ccee-10d8-4eb4-ab81-234234c9636",
   "W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
   "StatusTs": "2021-06-24 10:40:21 -04:00",
   "TINMatching": {
     "Status": "ORDER_CREATED",
     "StatusTs": "2021-06-24 10:40:21 -04:00",
     "StatusMsg": null,
     "Errors": null
   },
   "FormW9RequestType": "Email_API",
   "PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
   "Email": "steve@abcinc.com",
   "FormData": {
     "Line1Nm": "ABC Inc",
     "Line2Nm": null,
     "TINType": "EIN",
     "TIN": "XX-XXX1111",
     "Address": {
       "Address1": "123 E. Main St",
       "Address2": "Suite 400",
       "City": "Rock Hill",
       "State": "SC",
       "ZipCd": "29730"
     },
     "FederalTaxClassification": "C Corporation",
     "ExemptPayeeCd": "5",
     "ExemptFromFATCA": "F",
     "IsBackUpWH": false
   },
   "Errors": null
 },
 "FormW8Ben": null,
 "Errors": null
}

Extend your software with TaxBandits IRS E-file API Integration