Webhook
Webhooks notify your system whenever there is a status update on a recipient’s Form W-9/W-8 submission. The webhook payload includes key data such as the recipient’s name, address, TIN, and a secure download link for the completed form.
For detailed information, click here.
How to configure webhooks for Form W-9/W-8 status
-
Log in to the developer console.
- Sandbox : sandbox.taxbandits.com
- Live : console.taxbandits.com
-
Then navigate to Settings >> Webhooks.
-
Click ‘Add Webhook’. Choose the event type as 'WhCertificate Status Change’.

- Enter your Callback URL where you want to receive notifications and click Save. For WhCertificate, you can add up to 5 Webhook URLs and choose the Callback URL to which the Webhook response needs to be posted.
-
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 WhCertificate/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.

Request JSON with WebhookRef

Response Body
| Field | Type | Description |
|---|---|---|
| FormType | String | Type of Form (W-9 or W-8BEN). |
| WebhookRef | Guid |
|
| FormW9 | Object | Contains Form W-9 Information. |
| SubmissionId | Guid | A 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. |
| 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 | A unique identifier of the recipient |
| RecipientId | Guid | A unique ID generated by TaxBandits after the return is created and will be returned in the Response. You can use this ID for 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.
|
| PdfUrl | String | The URL to download the completed W-9. Note: This URL will expire in 24 hours. |
| 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 RequestByURL method. | |
| Phone | String | The phone number of the recipient |
| CountryPhoneCode | String | Recipient’s country code. |
| 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. |
| TINType | string | TIN type of the recipient. |
| TIN | string | Recipient’s TIN |
| Address | Object | Recipient’s complete address |
| Address1 | string | Recipient’s Address 1 (street address or post office box of that locality). This will be pre-filled on the Form. |