Overview

Tax filing involves multiple stages and status changes, making it important to stay informed as filings progress. To help you track these updates efficiently, the TaxBandits API uses Webhooks to notify your application of filing status changes and related events in real time.

Webhooks allow your application to receive automated, real-time notifications from our system whenever specific events occur. Instead of manually calling APIs to check for updates, webhooks push event data directly to a callback URL you define.

Using webhooks, you can automatically track changes such as filing status updates, recipient actions, processing milestones, and other system events as they happen.

Steps to configure webhooks

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

2. Add a webhook
   Click ‘Add Webhook’ and select the event type you want to subscribe to. Refer to the ‘Webhook event types’ section below for the full list of supported events.

3. Provide a callback URL
   Enter a valid HTTPS callback URL (maximum 500 characters).

   • 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.
   Using multiple callback URLs

   For certain webhook event types, you can configure multiple callback URLs in the TaxBandits Developer Console.

   • 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).

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

Best practices for callback URLs

To ensure successful and secure webhook delivery, follow these best practices:

• SSL certificate required: The callback URL must use HTTPS with a valid SSL certificate. HTTP URLs are not supported.
• IP whitelisting: Whitelist TaxBandits webhook IP addresses to prevent unauthorized access to your endpoint.
• Regular testing: Use the Sandbox Developer Console to send test notifications and confirm that your endpoint is active and responding correctly.

Note:

To understand webhook payloads and test integrations, you may use third-party webhook testing tools such as Webhook.site, PostBin, or RequestBin.

Webhook Event Types

You can configure webhooks for the following events:

• E-file Status Change (Federal)
  Triggered when a federal agency accepts or rejects a tax form. Learn More

• E-file Status Change (State)
  Triggered when a state agency accepts or rejects a tax form. Learn More

• Postal Mailing Sent
  Triggered when the recipient copies (1099, W-2, etc.) have been mailed successfully. Learn More

• Online Access Status Change
  Triggered when recipient copies (1099, W-2, etc.) are shared online, when recipients provide consent, or when they access the forms. Learn More

• New Business Added
  Triggered when a new business is added using the Business/RequestByUrl endpoint. The webhook payload includes complete payer details.
  Learn More

• Order Completion
  Triggered when a new order is completed. Learn More

• PDF Generation
  Triggered when a form PDF is generated using the GetPDF endpoint. The webhook payload includes the download URL for the PDF. Learn More

• Form 1099 Auto-Generation
  Triggered when Forms 1099 are auto-generated based on transaction data. Learn More

• Form W-9 Status Change
  Triggered when a recipient submits Form W-9. Includes TIN Matching status and the download URL for the completed form. Learn More

  If recipients submit either Form W-9 or Form W-8BEN, use the WhCertificate Status Change webhook instead.

• Form W-8BEN Status Change
  Triggered when a recipient submits Form W-8BEN. Learn More

  If recipients submit either Form W-9 or Form W-8BEN, use the WhCertificate Status Change webhook instead.

• WhCertificate Status Change
  Triggered when recipients submit either Form W-9 or Form W-8, based on citizenship. Learn More

• TIN Matching Status Change
  Triggered when the TIN Matching status changes. The payload includes:

  • TIN Matching order status
  • Timestamp of the status change
  • Remaining TIN Matching attempts for the recipient

  If TIN Matching is requested through the Form W-9 or WhCertificate endpoints, the TIN Matching status is included in the corresponding webhook. Learn More

• Instant TIN Matching
  Triggered when Instant TIN Matching is enabled to verify recipient or vendor TINs. Provides updates on the verification process. Learn More

• Form 8453-EMP Status Change
  Triggered when the taxpayer or tax preparer signs or declines to sign Form 8453-EMP. Learn More

• State Payroll Filings Status Change
  Triggered when a state agency accepts or rejects withholding or unemployment insurance (UI) forms. Learn More

• New Hire Status Change
  Triggered when a state agency accepts or rejects a new hire report. Learn More

• Downtime Alert
  Triggered when the TaxBandits API service is unavailable due to scheduled maintenance or an unexpected interruption.