Skip to main content
Version: 2.0.0

Online Access Status Change

This webhook provides real-time notifications about the recipient copies of 1099, W-2, etc., shared with the recipients via Online Access.

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 'Online Access Status Change'.

OnlineAccessStatusChange

  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.

  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​

The following are the different statuses available for tax forms shared with the recipients via online access.

  • EMAIL_SENT - An invitation email for online access has been sent to the recipient.
  • CONSENTED - The recipient has given consent for the portal.
  • CONSENTED_WITHDRAWN - The recipient has withdrawn consent for online access.
  • PDF_VIEWED - The recipient has viewed the PDF (e.g., 1099 NEC return).
  • PDF_DOWNLOADED - The recipient has downloaded the PDF.

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": "b870040d-fded-420b-b424-28bf0dd11261",
  "RecordId": "5e2433ef-0d2e-4d8d-beba-06dac739a9fc",
  "RecipientId": "f871240d-fded-420b-b424-28bf0dd11261",
  "PayeeRef": "Pe12345",
  "Email": "james@sample.com",
  "AccountNum": "2024123451234",
  "FormType": "FORM1099NEC",
  "ConsentStatus": "CONSENTED",
  "ConsentStatusTs": "2024-12-24 00:19:48 -05:00",
  "OnlineAccessStatus": "EMAIL_SENT",
  "OnlineAccessStatusTs": "2024-12-24 00:19:48 -05:00"
}

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.