Skip to main content
Version: 2.0.0

E-file Status Change (Federal)

This webhook provides real-time updates on the processing status of tax forms filed with federal agencies such as the IRS or SSA. This includes forms like 1099, W-2, 94x, ACA, and other form types supported by TaxBandits.

This event type also applies to correction filings.

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 ‘E-file Status Change (Federal)’.

E-fileStatusChange

  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 status codes available for tax forms filed with the federal agency.] For W-2 and 1099 forms:

  • Sent to Agency – The form has been transmitted and is awaiting acceptance or rejection
  • Accepted – The form has been accepted by the IRS/SSA
  • Rejected – The form has been rejected. Fix the errors and retransmit
  • ACCEPTEDWITHERRORS – The form was accepted with validation issues, and a correction must be filed
  • Yet_to_Retransmit – Updates have been made to the rejected form, and it is pending retransmission to the IRS/SSA

For 94x forms

  • Accepted – The form has been accepted by the IRS
  • Rejected – The form has been rejected. Fix the errors and retransmit

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 – 1099 e-file status change​

{
    "SubmissionId": "b870040d-fded-420b-b424-28bf0dd11261",
    "FormType": "FORM1099NEC",
    "Records": [
        {
            "RecordId": "5e2433ef-0d2e-4d8d-beba-06dac739a9fc",
            "RecipientId": "144b9ab4-d5a3-4d9c-bee1-4838e006e23b",
            "PayeeRef": "Payee001",
            "AccountNum": "123456",
            "Status": "Accepted",
            "StatusCode": 14,
            "FilingReference": null,
            "StatusTime": "2023-12-06T07:45:17.9647302-05:00",
            "RejectedBy": null,
            "Errors": null
        },
        {
            "RecordId": "5e2433ef-0d2e-4d8d-beba-06dac739a9fc",
            "RecipientId": "7a7d932b-de8d-41c4-a1f6-ff84cfe08775",
            "PayeeRef": "Payee002",
            "AccountNum": "213125",
            "Status": "Rejected",
            "StatusCode": 15,
            "FilingReference": null,
            "StatusTime": "2023-12-06T07:45:17.9647302-05:00",
            "RejectedBy": null,
            "Errors": [
                {
                    "Id": null,
                    "Code": "ERR-SAMPLE-001",
                    "Name": "Sample Field",
                    "Message": "Sample Error Message",
                    "Type": "Error"
                }
            ]
        }
    ]
}

Sample webhook payload – Form 941 e-file status change​

{
"Submissionld": "95a762b7-3a46-4b42-aa6c-ddac664cc95c",
"PayerRef": "Payer-1403-06",
"FormType": "Form941",
"Records": [
    {
    "Recordld": "6ec62ba9-6d8a-4c89-9106-023c862bfl4c",
    "Recipientld": null,
    "PayeeRef": null,
    "AccountNum": null,
    "Status": "Accepted",
    "StatusCode": 14,
    "FilingReference": {
        "FiledWith": "1RS",
        "RefNumber": "32133920250733204005",
        "ApprovalLetterPath": "https ://expressirsforms.s3.amazonaws.com/TempApprovalLetters/121762/6ec62ba9-6d8a-4c89-9106-023c862bf14c.pdf",
        "ElectronicPostMark": "2025-03-14T06: 36:39.027-04:00"
    },
    "StatusTime": "2025-03-14T06:39:57.6043399-04:00",
    "RejectedBy": null,
    "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.