Skip to main content
Version: 1.7.0

WhCertificate Status Change

When the recipients submit either W-9 or W-8BEN (based on their citizenship), you will be notified via this Webhook. This applies to the endpoint WHCertificate/RequestByUrl or WHCertificate/RequestByEmail. The Webhook payload will have W-8BEN details. It may also contain the TIN matching status and the URL to download the completed form (if you opted for it).

Steps to Configure Webhook​ for WhCertificate Status Change​

  1. Log in to the Developer Console Site. Navigate to Settings >> Webhook Notifications.

  2. Click the Add Webhook button and choose the Event Type as ‘WhCertificate Status Change’.

WhCertificate

  1. Enter the callback URL and click on the Submit button. Ensure that the callback URL you enter is valid, as the API will authenticate this URL by posting a sample JSON. The URL will be activated only when we receive the 200 response. You must follow these best practices to have a valid callback URL for Webhook.

  2. Then, provide a Notify email. This email will be used by TaxBandits to notify you regarding any failed attempts of Webhook posting.

Status Codes:​

Following are the different types of status codes that you will receive through Webhooks

For W-9 without TIN Matching​

  • Completed - The recipient has completed and signed the Form W-9

For W8-Ben​

  • Completed - The recipient has completed and signed the Form W8-BEN

For W8-BEN-E​

  • Completed - The recipient has completed and signed the Form W8-BEN-E

For W-9 with TIN Matching​

  • Order Created - The recipient completed the Form W-9, and a TIN Matching order is created in Taxbandits. The TIN Matching request is yet to be sent to the IRS.

  • Sent to Agency - The order has been sent to the IRS for TIN verification, and TaxBandits is waiting for the response from the IRS. Usually, the IRS takes one business day to complete the TIN verification process.

  • Success - The recipient’s Name and TIN combination match the records in the IRS database.

  • Failed - The recipient’s Name and TIN combination do not match the records in the IRS database.

Receive Webhook Requests from API​

Once the Webhooks are configured and the callback URL is authenticated by receiving a 200 response using a sample post, our API will start issuing an HTTP Post to the URL every time your recipients complete and submit either a W-9 or W-8 BEN. The request’s POST parameter will contain JSON data.

Here is the sample Webhook Post:

    {
        "FormType": "FormW9",
        "WebhookRef": "2172bffc-7bf6-40e2-8b82-41743838badc",
        "FormW9": {
            "SubmissionId": "5b5af1fc-f181-49b0-b019-b198ff31ef3b",
            "Requester": {
                "BusinessId": "6a0628bc-7b9c-40c6-9a39-b16848c45b88",
                "PayerRef": "178956",
                "BusinessNm": "Snowdaze LLC Commpany",
                "TINType": "SSN",
                "TIN": "XXX-XX-6526",
                "DBAId": null,
                "DBARef": null
            },
            "PayeeRef": "778811",
            "RecipientId": "0a1e0122-9874-485d-9e3d-2ee215c5c9d9",
            "W9Status": "COMPLETED",
            "StatusTs": "2023-12-11 06:40:03 -05:00",
            "TinMatching":{
                "Status": "SUCCESS",
                "StatusTs": "2023-12-11 06:40:03 -05:00",
                "StatusMsg": null,
                "Errors": null
            },
            "FormW9RequestType": "COMMON_URL_API",
            "PdfUrl": "https://s3.amazonaws.com/taxbandits-dev-api/9a24b362-459b-4f46-9765-48178cb219ca.Pdf",
            "Email": null,
            "FormData": {
                "Line1Nm": "Ferrick Krester",
                "Line2Nm": " ",
                "TINType": "EIN",
                "TIN": "XX-XXX5555",
                "Address":{
                    "Address1": "9256 PARKWAY E",
                    "Address2": "STE B",
                    "City": "BIRMINGHAM ",
                    "State": "AL",
                    "ZipCd": "35206"
                },
                "FederalTaxClassification": "Individual or Sole proprietor or Single-member LLC",
                "ExemptPayeeCd": null,
                "ExemptFromFATCA": null,
                "IsBackUpWH": false,
                "OtherDescription": null
            },
            "Errors": null
        },
        "FormW8Ben": null
    }

Respond to Webhook Post from API​

You must respond to the Webhook post by sending an HTTP 200 OK Response. Any other code other than 200 will be treated as an incomplete call. This API does not support 301 redirects, which will be treated as an error. Learn more

You are required to initiate a response to our Webhook request within 5 seconds, if not, the request will be treated as timeout. If the API doesn’t receive a response during the 5-second time window or in case of an error, it will attempt to retry the connection a total of 9 times within 24 hours.

Before you respond to a Webhook request, you must validate if the request was sent from TaxBandits. To learn how to validate Webhook requests, click here.