Webhook

Webhooks are used to notify clients when one of their recipients has completed the W-8BEN. The webhook payload includes W-8BEN data such as the recipient’s name, address, TIN(US/Foreign), as well as the link to download the completed form.

Go to Webhooks for information on Webhooks in TaxBandits.

Configure the Webhook for W-8BEN Status

1. Log in to the developer console.

   • Sandbox Console URL: sandbox.taxbandits.com
   • Live Console URL: console.taxbandits.com

2. Then navigate to Settings >> Webhooks.

3. Click the Add Webhook button and choose the Event Type as W8BEN Status Change while setting up your Webhook URL.

4. After entering the Callback URL, click on the Save button. Ensure that the callback URL is valid because the API will post a sample JSON. The callback URL is expected to return HTTP 200 response code in order to remain active. If the API doesn’t return 200 response code, then the callback URL will go inactive. You can retry posting the sample data to make the callback URL Active.

Response Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission
Requester	object	Requester information.
BusinessId	Guid	Unique identifier of a 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
W8BENStatus	String	Status of the W-8BEN.
StatusTs	String	Timestamp of the W-8BEN Status.
FormW8BENRequestType	String	Form W-8BEN requested Type. URL_API - Form W-8BEN was requested using the API method RequestByURL. Email_API - Form W-8BEN was requested using the API method RequestByEmail. Email_UI - Form W-8BEN was requested from the TaxBandits UI application.
PdfUrl	String	URL to download the completed W-8BEN. Note: This URL will expire in 24 hours.
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.
Address1	string	Recipient’s Address 1 (street address or post office box of that locality). This will be pre-filled on the Form.
Address2	string	Recipient’s Address 2 (suite or apartment number). This will be pre-filled on the Form.
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.
Address1	string	Recipient’s Address 1 (street address or post office box of that locality). This will be pre-filled on the Form.
Address2	string	Recipient’s Address 2 (suite or apartment number). This will be pre-filled on the Form.
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 person behalf, enter the capacity in which they are acting.
Errors	Object	Shows detailed error information.

Sample Webhook Response: The recipient has completed Form W-8BEN, and the status has been changed to “Completed.” It will be notified to clients via Webhook. PdfUrl is provided to download the completed W-8BEN.

{
   "SubmissionId": "4a36dc14-f059-4c89-83cd-ff9e350ed0a0",
   "Requester": {
       "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
       "BusinessNm": "Snowdaze LLC",
       "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": "sample@bodeem.com",
   "FormData": {
       "NmOfIndividual": "Joseph Smith",
       "CitizenOfCountry": "Canada",
       "USTINType": "SSN",
       "USTIN": "111-11-1111",
       "ForeignTIN": null,
       "DOB": "07/08/1990",
   "PermanentAddress": {
       "Address 1": "123",
       "Address 2": "E. Main St",
       "CityState": "Chennai,Tamilnadu",
       "Country": "India",
       "PostalCd": "29730"
      },
   "MailingAddress": {
       "Address1": null,
       "Address2": null,
       "City": null,
       "State": null,
       "Country": null,
       "PostalCd": null
  },
  "TaxTreatyBenefits": {
      "BeneficiaryCountry": "Canada",
      "ClaimingProvArticlePara": "VII",
      "RateOfWH": "27.50",
      "TypeOfIncome": "Royalties",
      "AdditionalConditions": null
 },
  "Signature": {
      "SignerNm": "Joseph",
      "CapacityInWhichActing": "Guardian"
  },
},
"Errors": null,
}