The API uses webhooks to notify users on the status of tax forms filed. Through this, the API gains an advantage to send a notification through an HTTP post as well as to respond to the same request more information.
The user must configure webhooks from the developer control panel. Right now, the scope of this communication is limited to the status of tax forms.
Receive webhook request from API
- Log in to the developer control panel. Go to Settings >> Webhooks.
- Enter the Callback URL and click on the Submit button. Ensure that the callback URL is valid as the API will post a sample JSON. The callback URL is expected to return HTTP 200 response code in order to remain active. If the API doesn’t return 200 response code, then the callback URL will go to inactive. You can retry posting the sample data to make the callback URL Active.
The API will issue an HTTP Post to the webhook URL every time when the status gets updated for a tax return. The request’s POST parameter will contain JSON data.
Respond to a webhook request from API
The user must respond to the webhook request 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.
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 for a total of 18 times over the next 48 hours.
We recommend users to respond to the webhook request at the earliest before initiating other internal communication processes. For example, if you wish to notify users whose returns were rejected by the IRS, the first thing you should do is to initiate a response to the webhook event by giving HTTP 200 OK response, and then attempt to email the rejected users. In this way, sending emails doesn’t get blocked while responding to webhook.
Security of Webhooks
Before you respond to a webhook request, validate if the request has been sent by the ExpressTruckTax Webhooks. To verify the authenticity, check if the webhook post has the signature on the header. And then, match it with the HMAC digest computed using the algorithm below. If both the components match, you can be assured that the webhook request was sent by ExpressTruckTax.
Below is what you need to do:
Retrieve the Public Key from the user repository. This is the same public key that was provided in the developer control panel.
Read the Timestamp and the Signature from the header.
Use the Public Key and the Timestamp to compute the HMAC hash using SHA 256 algorithm.
The signature generated in the header must match with the hash generated with Step 3.
- If there is a match, parse the JSON data for further processing.
- If there is no match, send the Response as 401 and stop processing.