Skip to main content
Version: 2.0.0

Form W-9 Status Change

This webhook can be configured to receive real-time notifications about the status of W-9 requests initiated from TaxBandits API. Applicable to FormW9 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 WhCertificate endpoint, please configure the webhook event type 'WhCertificate 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 'Form W-9 Status Change'.

Form W-9

  1. 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, FormW9/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).

  2. 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 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 (if opted) 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​

    {
    "SubmissionId": "15234kc7-a3cc-4283-892a-65bd0206979e",
    "WebhookRef":"99db0874-e749-48d6-b96f-de6447d03667",
    "Requester": {
        "BusinessId": "16b7bl6c-1865-4740-9ef9-a0de62157af3",
        "PayerRef": "Snow123",
        "BusinessNm": "Snowdaze LLC",
        "FirstNm": null,
        "MiddleNm": null,
        "LastNm": null,
        "Suffix": null,
        "TINType": "EIN",
        "TIN": "34-3986789",
        "DBAId": null,
        "DBARef": null
    },
    "PayeeRef": "W93229",
    "RecipientId": "60b31480-3951-403c-8902-ff66d0203253",
    "W9Status": "COMPLETED",
    "StatusTs": "2024-11-25 01:37:18 -05:00",
    "TINMatching": null,
    "FormW9RequestType": "URL_API",
    "PdfUrl": "https://s3.amazonaws.com/taxbandits-sb-api/9413f5af-7b82-4da7-9d1d-3ca12572b3af.Pdf",
    "Email": null,
    "FormData": {
        "Line1Nm": "Shawn",
        "Line2Nm": "Dairy Delights LLC",
        "FirstNm": null,
        "MiddleNm": null,
        "LastNm": null,
        "Suffix": null,
        "TINType": "EIN",
        "TIN": "11-8338476",
        "Address": {
            "Address1": "71 SAINT NICHOLAS DR",
            "Address2": null,
            "City": "NORTH POLE",
            "State": "AK",
            "ZipCd": "99705-7752"
        },
        "AccountNum": "Pe3229",
        "FederalTaxClassification": "Individual or Sole proprietor or Single-member LLC",
        "IsLine3b": false,
        "ExemptPayeeCd": null,
        "ExemptFromFATCA": null,
        "IsBackUpWH": false,
        "IsDAExemptBroker": false
    },
    "Errors": 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.