Webhooks allow you to automatically push data from your Tap Inspect account to a third-party party service when certain events occur. Webhooks will be triggered by activities from any member of your team that meets the criteria you set.
Webhooks are sent to the URL that you specify as HTTP POST requests. The body of the request is provided in JSON format and will always contain the following base keys:
|id||An integer ID to uniquely identify the webhook request. You can use this ID to identify webhooks you have already received and processed in order to avoid duplicates.|
|event||This specific event that triggered the webhook|
|payload||A hash of keys and values specific to the event. See the table of events below to find what the payload should look like for different scenarios.|
Acknowledgment and Automatic Retries
Upon receipt of a webhook, you should accept it by returning an HTTP “200 OK” response as quickly as possible. Sending any other response (i.e. “500 Internal Server Error”, “404 Not Found”, etc.) OR failing to return a response within approximately 15 seconds will result in automatic retries of the webhooks.
Tap Inspect will attempt to send each webhook event 5 times before giving up. The webhook retries will follow a backoff schedule:
|1||As soon as possible after the original event|
|2||10 seconds after the most recent failure|
|3||15 seconds after the most recent failure|
|4||90 seconds after the most recent failure|
|5||180 seconds after most the recent failure|
If you use the "Resend Webhook" feature on the webhook's integration webpage, please be aware that it is possible to perform a manual resend while automatic retries are still active. Because of this, it is your responsibility to avoid taking duplicate action. Suggestions for avoiding duplicate actions are:
- Use the unique webhook ID to remember which web hooks you've already processed
- Do not attempt to retry a webhook until the status has changed to "Failed" instead of "Retrying"
The following Tap Inspect events are available as triggers for webhooks:
|on_publish||A report or job is published||Identical to the Get Job API response with the expanded flag set|
You can verify that the contents of a webhook are authentic by evaluating the signature sent in the accompanying HTTP request header named X-TI-Webhook-Signature-Hmac-Sha-256.The signatures generated by taking a X digest of the raw HTTP body of the webhook request and your team's webhook shared key.
In Ruby, you could verify the signature with the following code:
OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), webhook_shared_key, webhook_body)
For example, if you received a webhook with the following request body:
And your team's webhook shared key is:
Then the webhook signature will equal:
Finding Your Team's Webhook Shared Key
When you create an account, your team's shared key is generated automatically for you. You can find it on the Webhook Integration settings page described below. Please protect this key as you would a password, since it could allow an intruder to create false webhook's that would pass your system's signature verification test.
Point your web browser to https://app.tapinspect.com/integrations (login with your email and password if needed) and click on Change Settings in the Webhooks box.
You will be presented with a list of any webhooks you have already configured, along with a box that shows you what your team's webhook shared key is for use in verification. To add a new webhook, simply click on "Add a New Webhook".
Enter the URL you wish to receive the webhook, and select which event subscriptions should trigger it. When you are ready, click on "Save Changes".
You will now see your new webhook listed on the following screen.
From the list of webhooks, click on the webhook you are interested in testing. You will be taken to the webhook details view. To send a webhook to your target URL, click on the button "Send Test Webhook".
The test webhook that is sent will have the following payload:
The results of the test will appear at the bottom of the screen. You can click on an individual row to expand the results and see details such as the response received from the target URL.
You may optionally click on the "Resend Webhook" button to send the same webhook again.