Webhook
Webhooks are used to notify you regarding the status of W-9/W-8 completion by the recipients. The webhook payload includes W-9/W-8 data such as the recipient’s name, address, EIN/SSN, as well as the link to download the completed form.
For WhCertificate, you can add up to 5 Webhook URLs and choose the Callback URL to which the Webhook response needs to be posted.
To do that, store the unique reference we generate against each Callback URL at your end. Then, pass the reference in the request JSON. If the Webhook reference is not passed, we will post the Webhook response to the default Callback URL.
The webhook payload includes the recipient data, including the Name, Address, Country of citizenship, and TIN number, along with the link to download the completed Form W-9 or W-8BEN.
How does it work?
-
Log in to the developer console.
- Sandbox Console URL: sandbox.taxbandits.com
- Live Console URL: console.taxbandits.com
-
Then navigate to Settings >> Webhooks.
-
To add multiple webhook Callback URLs inside the console site, click on the Add Webhook button.
- On the Add Webhook pop-up, choose the Event Type as WhCertificate Status Change. Once you select the event type, you will have the option to add up to 5 webhook Callback URLs.
- Upon Saving, TaxBandits generates a unique Webhook Reference (GUID) against each Callback URL. Store these Webhook References at your end and pass them in the request JSON for us to 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 (Callback URL 1).
6.When you call the WhCertificate/RequestByUrl endpoint, you can mention the preferred Callback URL by sending the stored Webhook Reference to the node WebhookRef. The WebhookRef node is optional.
When a recipient completes the W-9/W-8BEN, the webhook will be posted to the Callback URL that is tied to the WebhookRef given in the request.
If you do not specify the WebhookRef in the request, then the webhook will be posted to the default Callback URL.
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. |