WhCertificate Status Change

This webhook can be configured to receive real-time notifications about the status of W-9/W-8 requests initiated from TaxBandits API. Applicable to WhCertificate Status Change endpoint.

• If you have opted for TIN Matching along with the W-9 request, the webhook response will also include the TIN Matching status.

• By default, the webhook response will include the recipient's TIN. If you prefer not to include the TIN, you can adjust this preference in the console. See how

• If you've used FormW9 endpoint, please configure the webhook event type 'Form W-9 Status Change'.

Steps to configure

1. Log in to Developer Console
   Navigate to 'Settings' → 'Webhook Notifications'.

2. Add a webhook
   Click 'Add Webhook' and select the event type 'WhCertificate Status Change'.

3. Provide a callback URL
   Enter a valid HTTPS callback URL (maximum 500 characters). You can add upto 5 callback URLs in the TaxBandits Developer Console. Ensure that your callback URL follows these best practices.

   • The API validates this URL by sending a sample JSON payload.
   • The webhook will be activated only after your endpoint responds with an HTTP 200 status code.
   Instructions when using multiple callback URLs

   • When you save 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 (for example, WhCertificate/RequestByUrl), you can specify the preferred callback URL by including the corresponding WebhookRef in the request JSON.

   • The WebhookRef node is optional. If provided, webhook notifications for that request will be sent to the callback URL associated with the specified Webhook Reference.

   • If WebhookRef is not specified, webhook notifications will be sent to your default callback URL (typically Callback URL 1).

4. Configure a notification email
   Provide a notification email address. TaxBandits will use this email to alert you if webhook delivery attempts fail.

Statuses available

Following are the different types of status that you will receive.

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

Webhook responses include two status objects:

• 'W9Status' – Reflects the Form W-9 completion status.

  • COMPLETED - The recipient has completed and signed the Form W-9.
  • COMPLETED_AND_TIN_MATCH_INPROGRESS - Form W-9 has been completed, and TIN Matching is yet to be completed. TIN Matching is applicable only for completed Form W-9.
  • INVALID – The W-9 form has been marked as invalid since the TIN Matching has failed.

• 'TINMatching' – Reflects the TIN Matching status

  • ORDER_CREATED - The recipient completed the Form W-9, and the TIN Matching order is created in TaxBandits.
  • 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.

Receiving webhook requests

Once the webhook is configured and the callback URL is successfully authenticated, TaxBandits will send an HTTP POST request to your callback URL whenever a filing status changes.

Each request contains a JSON payload with submission details and record-level status information.

Sample webhook payload

   {
  "FormType": "FormW9",
  "WebhookRef": "4e883d08-ccb0-4e92-a83b-196d763d7409",
  "FormW9": {
    "SubmissionId": "b2a54c3a-37de-4cd7-912c-fad5e8ac713b",
    "RecordId": null,
    "Requester": {
      "BusinessId": "51cd2f9f-046c-47c4-988f-7f83c2bdd3ee",
      "PayerRef": "Pe7369",
      "BusinessNm": "SnowDaze LLC",
      "FirstNm": null,
      "LastNm": null,
      "MiddleNm": null,
      "Suffix": null,
      "TINType": "EIN",
      "TIN": "73-3746874",
      "DBAId": null,
      "DBARef": null
    },
    "PayeeRef": "PayeeRef01",
    "RecipientId": "ae9d561d-4ea6-4c6c-a9a7-81d37e70031f",
    "W9Status": "COMPLETED",
    "StatusTs": "2025-10-13 06:41:53 -04:00",
    "TINMatching": {
      "Status": "SUCCESS",
      "StatusTs": "2025-10-13 06:41:53 -04:00",
      "StatusMsg": null,
      "Errors": null
    },
    "FormW9RequestType": "COMMON_URL_API",
    "PdfUrl": "https://s3.amazonaws.com/taxbandits-dev-api/e094a339-fd41-4846-a683-435e97a4c4454.Pdf",
    "Email": null,
    "FormData": {
      "Line1Nm": "James Smith",
      "Line2Nm": "Technologic",
      "FirstNm": "James",
      "MiddleNm": null,
      "LastNm": "Smith",
      "Suffix": null,
      "TINType": "SSN",
      "TIN": "XXX-XX-7346",
      "Address": {
        "Address1": "71 Saint",
        "Address2": null,
        "City": "NORTH POLE",
        "State": "AK",
        "ZipCd": "99705",
        "Country": "US"
      },
      "AccountNum": null,
      "FederalTaxClassification": "Individual or Sole proprietor or Single-member LLC",
      "IsLine3b": false,
      "ExemptPayeeCd": null,
      "ExemptFromFATCA": null,
      "IsBackUpWH": false,
      "IsDAExemptBroker": false
    },
    "Errors": null
  },
  "FormW8Ben": null,
  "FormW8BenE": null,
  "FormW8ECI": null,
  "FormW8IMY": null,
  "FormW8EXP": null
}

Responding to webhook requests

Your application must respond with HTTP 200 OK to acknowledge receipt of a webhook request.

• Any response other than 200 is treated as a failed delivery
• HTTP redirects (301) are not supported and are treated as errors
• Your endpoint must respond within 5 seconds, or the request is considered a timeout

If a webhook delivery fails or times out, TaxBandits will retry the request up to 9 times within 24 hours.

Validating webhook requests

Before processing a webhook payload, you must verify that the request originated from TaxBandits.Refer to the Webhook validation documentation to learn how to authenticate incoming webhook requests.