Webhook

Webhooks notify your system whenever there is a status update on the TIN Matching request for a recipient. The webhook payload includes key data such as the recipient’s name, TIN, the current status of the TIN Matching request, and any relevant error messages if the request failed.

Go to Webhooks for information on Webhooks in TaxBandits.

How to configure webhooks for TIN Matching 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 Add Webhook. Choose the event type as TIN Matching Status Change.

4. 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 TINMatchingRecipients/Request 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 an 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.

Response Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission.
WebhookRef	Guid	A unique identifier of the Webhooks that TaxBandits generates against each Callback URL when adding it to 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.
Business	object	Object to identify the Business Details.
BusinessId	Guid	An unique identifier of the business.
TIN	String	Taxpayer Identification Number of the business.EIN for a company and SSN for an Individual.
PayerRef	string	An unique identifier for each payer completing their information. This identifier can be used in future references of the payer in the API.
RecordId	Guid	Unique identifier of the record.
SequenceId	String	Unique record identifier set by the client.
RecipientId	String	Unique identifier of the recipient.
Name	String	Name of the recipient.
TINType	String	TIN Type of the recipient.
TIN	String	Taxpayer Identification Number of the recipient.
Status	String	TIN Matching order status.
StatusTs	String	Timestamp of the TIN Matching status.
NumOfAttemptsRmng	String	Number of TIN Matching attempts remaining for the TIN in TaxBandits.
Errors	object	Shows detailed error information in the request.

Webhook Response for Success Status

{
  "SubmissionId": "1e13a2d4-a3de-4902-8e3b-e9fe7ebb2122",
  "WebhookRef":"99db0874-e749-48d6-b96f-de6447d03667",
   "Business": {
    "BusinessId": "a3b70845-669c-43ad-bdca-bfaeb4b3d7e4",
    "TIN": "14-5258330",
    "PayerRef": "snowdaze001"
  },
  "RecordId": "bb48cf2b-9871-4a9e-b45b-c8a50d749252",
  "WebhookRef": "e45cf17c-54ef-412d-bd36-456bd990a494",
  "SequenceId": "01",
  "RecipientId": "e60c6503-0927-4685-b827-c4943f0757fc",
  "PayeeRef": null,
  "Name": "Alex",
  "TINType": "ITIN",
  "TIN": "XXX-XX-3747",
  "Status": "SUCCESS",
  "StatusTs": "2025-10-13 07:27:46 -04:00",
  "NumOfAttemptsRmng": 2,
  "Errors": null
}

Webhook Response for Failed Status

{
 "SubmissionId": "e26580d0-c533-48d1-b177-cce38d95b5c3",
 "WebhookRef":"99db0874-e749-48d6-b96f-de6447d03667",
 "RecordId": "aa2f9641-74f1-49ec-8635-02576a8878df",
 "SequenceId": "A12345",
 "RecipientId": null,
 "Name": "Steve Smith",
 "TINType": "SSN",
 "TIN": "121-23-7900",
 "Status": "FAILED",
 "StatusTs": "2025-05-06 21:27:05 -04:00",
 "NumOfAttemptsRmng": 2,
 "Errors": null
}