Skip to main content
Version: 1.7.3

E-file Status Change Webhook

TaxBandits API allows you to use Webhooks to retrieve the status of filed tax forms.

In order to use the E-file Status Change Webhook, you must configure the Webhook Callback URL in the Developer Console.

This Webhook Event will trigger the status changes for the W-2, 1099, 5498, 94x and 1095-C forms

Steps to Configure Webhook​ for E-file Status Change​

  1. Log in to the Developer Console Site. Navigate to Settings >> Webhook Notifications

  2. Click the Add Webhook button and choose the Event Type as ‘E-File Status Change’.

E-fileStatusChange

  1. Enter the callback URL and click on the Submit button. Ensure that the callback URL you enter is valid, as the API will authenticate this URL by posting a sample JSON. The URL will be activated only when we receive the 200 response. You must follow these best practices to have a valid callback URL for Webhook.

  2. Then, provide a Notify email. This email will be used by TaxBandits to notify you regarding any failed attempts of Webhook posting.

Status Codes​

Following are the different types of form statuses that you will receive through Webhooks:

For W-2/1099 Forms:

  • Under Process - Our efile system is processing the form, which will be sent to the agency soon.
  • Sent to Agency - The Form has been sent to the agency and is yet to be accepted/rejected.
  • Accepted - The form is accepted by the IRS.
  • Rejected - The form is rejected by the IRS due to some errors. Please correct the errors and retransmit them.

For 94x Forms:

  • Accepted - The form is accepted by the IRS.
  • Rejected - The form is rejected by the IRS due to some errors. Please correct the errors and retransmit them.

Receive Webhook Requests from API​

Once the Webhooks are configured, and the callback URL is authenticated by receiving a 200 response using a sample post, our API will start issuing an HTTP Post to the URL every time the status of a tax return gets updated. The request’s POST parameter will contain JSON data.

Here is the sample Webhook Post for 1099-NEC Form 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"
                    }
                ]
            }
        ]
    }

Here is the sample Webhook Post for Form 941 E-file Status Change:

    {
        "SubmissionId": "1b24101f-e202-4ea6-89f3-8abe0f9c9a94",
        "FormType": "Form941",
        "Records": [
            {
            "RecordId": "120170a9-8b18-45e0-9604-1aa4bdecbd7d",
            "RecipientId": null,
            "PayeeRef": null,
            "AccountNum": null,
            "Status": "Accepted",
            "StatusCode": 14,
            "FilingReference": {
                "FiledWith": "IRS",
                "RefNumber": "32133920243303200002",
                "ApprovalLetterPath": "https://expressirsforms.s3.amazonaws.com/TempApprovalLetters/33854/120170a9-8b18-45e0-9604-1aa4bdecbd7d.pdf",
                "ElectronicPostMark": "2024-11-25T06:04:20.513-05:00"
            },
            "StatusTime": "2024-11-25T06:07:20.4442414-05:00",
            "RejectedBy": null,
            "Errors": null
            }
        ]
    }

Respond to Webhook Post from API​

You must respond to the Webhook post by sending an HTTP 200 OK Response. Any other code other than 200 will be treated as an incomplete call. This API does not support 301 redirects, which will be treated as an error. Learn more

You are required to initiate a response to our Webhook request within 5 seconds, if not, the request will be treated as timeout. If the API doesn’t receive a response during the 5-second time window or in case of an error, it will attempt to retry the connection a total of 9 times within 24 hours.

Before you respond to a Webhook request, you must validate if the request was sent from TaxBandits. To learn how to validate Webhook requests, click here.