Skip to main content
Version: 2.0.0

New Hire Report Status Change Webhook

This webhook can be configured to receive real-time notifications regarding the status of state new hire reports filed through TaxBandits API.

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 Hire Report Status Change’.

PostalSent

  1. 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.
  1. Configure a notification email
    Provide a notification email address. TaxBandits will use this email to alert you if webhook delivery attempts fail.

Statuses available​

The following are the different statuses available.

  • SENT_TO_AGENCY - The state form has been sent to the state agency and is awaiting the result.
  • ACCEPTED - The state form is accepted by the state agency.
  • REJECTED - The state form is rejected by the state agency.

Receive 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": "7078b9a5-0a2b-4c3b-84ed-cb7184e28438",
    "PayerRef": null,
    "SubmissionId": "01995c47-8d72-75de-89a0-4b5f049e4355",
    "Records": [
      {
        "EmployeeId": "13698b4f-b761-406b-b29e-1822f7a8b3b7",
        "EmpRef": "Pe5097",
        "RecordId": "01995c47-8f35-7298-9a9e-4a00d60abb3d",
        "State": "SC",
        "Status": "ACCEPTED",
        "StatusCode": "NH004",
        "StatusTs": "2025-09-18T02:04:37.6690000-04:00",
        "Info": null,
        "FilingReference": {
          "FiledWith": null,
          "FilingRef": "NH-SC-25-261-0012"
        },
        "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.