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.
FirstNm	string	First Name of the Individual
MiddleNm	string	Middle Name of the Individual
LastNm	string	Last Name of the individual
Suffix	string	Suffix of the Individual
TINType	string	TIN Type of the Requester.
TIN	string	Taxpayer Identification Number of the requester.
DBAId	String	Unique Identifier for the DBA.
DBARef	String	Unique identifier for each DBA. This identifier can be used in future references of the DBA in the API.
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 RequestByURL method. Email_API - Form W-8BEN was requested using the RequestByEmail method. 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.
IsFTINNotLegallyRequired	Boolean	When TRUE, Identifies that benificial owner on line 1 is not legally required to obtain an FTIN from their jurisdiction of residence.
ReferenceNum	string	Recipient’s reference number. You can use this field to enter any identification number you have for the recipient.
DOB	string	Date of Birth of the recipient
PermanentAddress	Object	Recipient’s permanent address.
Address1	string	Recipient US Address 1 (street address or post office box of that locality). This will be pre-filled on the Form.
Address2	string	Recipient US 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": "cc8800ac-af79-4dd2-9c5c-89bd84f5ba5c",
  "Requester": {
    "BusinessId": "ecef4552-34cf-4b65-aae8-ac74bc1ec484",
    "PayerRef": "Pay140054",
    "BusinessNm": "Snowdaze LLC",
    "FirstNm": null,
    "MiddleNm": null,
    "LastNm": null,
    "Suffix": null,
    "TINType": "EIN",
    "TIN": "XX-XXX8383",
    "DBAId": null,
    "DBARef": null
  },
  "PayeeRef": "abc123",
  "RecipientId": "ef19604c-6797-461e-9b16-73212c131e4a",
  "W8BENStatus": "COMPLETED",
  "StatusTs": "2024-07-30 03:33:04 -04:00",
  "FormW8BENRequestType": "URL_API",
  "PdfUrl": "https://s3.amazonaws.com/taxbandits-sb-api/e215d180-6803-4306-81ac-70f82b6f7034.Pdf",
  "Email": null,
  "FormData": {
    "NmOfIndividual": "Shawn Willams",
    "CitizenOfCountry": "Canada (CA)",
    "USTINType": "SSN",
    "USTIN": "723-67-2388",
    "ForeignTIN": null,
    "IsFTINNotLegallyRequired": true,
    "ReferenceNum": "76895",
    "DOB": null,
    "PermanentAddress": {
               "Address1": "120 Bremner Blvd",
               "Address2": "Suite 800",
               "City": "Toronto",
               "ProvinceOrStateNm": "Ontario",
               "Country": "Canada",
               "PostalCd": "4168682600"
           },
    "MailingAddress": {
               "Address1": "120 Bremner Blvd",
               "Address2": "Suite 800",
               "City": "Toronto",
               "ProvinceOrStateNm": "Ontario",
               "Country": "Canada",
               "PostalCd": "4168682600"
           },
    "TaxTreatyBenefits": {
      "BeneficiaryCountry": null,
      "ClaimingProvArticlePara": null,
      "RateOfWH": "0.0",
      "TypeOfIncome": null,
      "AdditionalConditions": null
    },
    "Signature": {
      "SignerNm": "Shawn Willams"
    }
  },
  "Errors": null
}