Webhook

Use webhooks to receive automatic status updates when a recipient opens, completes, or submits a W-8BEN form. Instead of checking the status manually, TaxBandits sends the update directly to your callback URL.

Here are the steps to configure webhooks for Form W-8BEN status

1. Log in to the Developer Console

Go to the appropriate console based on your environment:

Environment	URL
Sandbox	sandbox.taxbandits.com
Live	console.taxbandits.com

2. Go to Webhook Settings

From the Developer Console, navigate to Settings > Webhooks. Then click Add Webhook.

3. Select the Event Type

Choose the event type: Form W-8BEN Status Change. This event notifies your system whenever the recipient's W-8BEN form status changes.

4. Add Your Callback URL

Enter the callback URL where TaxBandits should send webhook notifications.

Your callback URL must be:

• Publicly accessible
• Able to receive POST requests
• Configured to return HTTP 200

When TaxBandits sends a sample or live webhook payload, your server must return an HTTP status code 200. If your server does not return 200, the webhook will become inactive. You can retry the sample payload from the Developer Console to reactivate it.

5. Save the Webhook

After saving, TaxBandits generates a unique WebhookRef for that callback URL.

Store this WebhookRef in your system. You can use it later to decide which callback URL should receive updates for a specific Form W-8BEN request.

6. Use WebhookRef in API Requests

When making Form W-8BEN API requests, such as FormW8Ben/RequestByUrl, you can include the WebhookRef.

If you include WebhookRef, updates will be sent to the callback URL linked to that reference.

If you do not include WebhookRef, updates will be sent to your default callback URL.

7. Receive Status Updates

Once configured, TaxBandits sends webhook notifications whenever the Form W-8BEN status changes.

The webhook may include:

• Recipient name
• Address
• TIN
• Form type
• Form status
• TIN Matching status
• Submission timestamp
• Secure PDF download link

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
}