New Business Added

This webhook event can be configured to receive real-time notifications when a new business (payer or employer) is added to TaxBandits API using the Business/RequestByUrl endpoint. The webhook payload will contain the completed details of the business.

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 'New Business Added'.

3. Provide a callback URL
   Enter a valid HTTPS callback URL (maximum 500 characters). 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.

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

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

    {
        "BusinessId": "6a0628bc-7b9c-40c6-9a39-b16848c45b88",
        "PayerRef": "178956",
        "BusinessNm": "Snowdaze LLC Company",
        "TINType": "SSN",
        "TIN": "XXX-XX-6526",
        "Email": "sample@bodeem.com",
        "Phone": "(478) 125-6352",
        "IsForeign": false,
        "USAddress": {
            "Address1": "42417 HWY 195",
            "Address2": "Suite 47A1",
            "City": "HALEYVILLE",
            "State": "AL",
            "ZipCd": "35565"
        },
        "ForeignAddress": 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.