Webhooks

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:

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:

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"

Events

The following Tap Inspect events are available as triggers for webhooks:

Webhook Verification

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:

{"id":8,"event":"test","payload":{"test":"Hello there!"}}

And your team's webhook shared key is:

632297b0-b9ef-0136-8b00-6c4008b3b8a2

Then the webhook signature will equal:

cc74b8bd3d2fef7d122f703ecf0a74ac54e1b21d38608f14263ccd9cef5ec5ff

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.

Configuring Webhooks

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.

Testing Webhooks

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:

{"id":8,"event":"test","payload":{"test":"Hello there!"}}

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.