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.

For detailed information, Click here.

How to configure webhooks for W-8BEN status

1. Log in to the developer console.

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

2. Navigate to Settings >> Webhooks.

3. Click ‘Add Webhook’. Choose the event type as ‘Form W-8BEN Status Change’.

4. Enter your Callback URL where you want to receive notifications and click Save. You can add up to 5 Webhook URLs and choose the Callback URL to which the webhook response needs to be posted.
   

   Note:

   • Upon saving a webhook in TaxBandits, a unique Webhook Reference (GUID) is generated for each Callback URL you register.

   • Store these Webhook References on your end. When making API requests (e.g., to the FormW8BEN/RequestByUrl endpoint), you can specify the preferred Callback URL by including the corresponding WebhookRef in the request JSON.

   • The WebhookRef node is optional. If you provide a WebhookRef, the webhook notifications for that request will be sent to the Callback URL tied to the specified Webhook Reference.

   • If you do not specify a WebhookRef, webhook notifications will be sent to your default Callback URL (usually Callback URL 1).

   • Ensure your callback URL is valid and publicly accessible. Upon saving, the API sends a sample JSON payload to your callback URL.

   • Your server must respond with HTTP status code 200 to keep the webhook active.

   • If your callback URL does not return HTTP 200, the webhook will become inactive. You can retry posting sample data to reactivate it.

info

By default, the webhook response will include the recipient’s TIN. If you prefer not to include the TIN, you can adjust this preference in the console. See how

Response Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission
WebhookRef	Guid	A unique identifier of the Webhook that TaxBandits generates 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.
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.
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 Response: The recipient has completed Form W-8BEN, and the status has changed to Completed. A webhook notification is sent to clients to inform them of this update. The payload includes a PdfUrl that provides a secure link to download the completed Form W-8BEN.

{
  "SubmissionId": "cc8800ac-af79-4dd2-9c5c-89bd84f5ba5c",
  "WebhookRef":"99db0874-e749-48d6-b96f-de6447d03667",
  "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,
    "ExpiryDate": "05/01/2028",
    "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
}

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

{
  "SubmissionId": "dbeb2b22-ab08-4650-a6ab-e3ef1719c11c",
  "WebhookRef": null,
  "Requester": {
    "BusinessId": "719a1a65-e3f1-46ca-9043-6d2d4e573958",
    "PayerRef": "PR001",
    "BusinessNm": "Snowdaze LLC",
    "FirstNm": null,
    "MiddleNm": null,
    "LastNm": null,
    "Suffix": null,
    "TINType": "EIN",
    "TIN": "43-7278383",
    "DBAId": null,
    "DBARef": null
  },
  "PayeeRef": "Pe8332",
  "RecipientId": "490767c0-5278-452d-b21f-82a021f3522c",
  "W8BenStatus": "EXPIRED",
  "StatusTs": "2025-04-10 00:01:38 -04:00",
  "FormW8BenRequestType": "URL_API",
  "PdfUrl": null,
  "Email": null,
  "FormData": null
}