Webhooks

TIS Training offers webhooks as a way to listen for events from your users. When the specified event occurs, we can send notice of the event to an endpoint you specify, along with some data about the event.

Subscribing to Events

You can add a URL to receive events here, or you add them via the View Webhooks button in the organisation config section of the administration panel. To create a webhook:

1. Click Add Webhook

2. Choose the type of event you'd like to subscribe to for this webhook.

3. Enter the URL you would like the events to be sent to. This URL must use the HTTPS scheme.

4. Click Add

A POST will be sent to the URL specified with a TEST_EVENT event type. Details about the schema of a webhook event, and the specific event data, can be found in the Webhook Reference section. Your server must return a success response code (200-299) for the webhook to be added. All webhook events are sent using the POST method.

Once the webhook is added, you will be shown a validation secret. Make sure you record this secret for the next section, as it will not be shown again.

Validating Events

All events except for the TEST_EVENT will be sent with a header called TapIntoSafety-Signature. You can use this header to verify that events have been sent from Tap into Safety. In order to do this, generate a HMAC-SHA256 signature of the body of the event. The validation secret is a base64 representation of the key for the signature. An example in JavaScript is below.

const message = '(The JSON payload of the event)';
const signature = "(The content of the TapIntoSafety-Signature header)";
const SECRET = "(Your validation secret)";

const algorithm = { name: "HMAC", hash: "SHA-256" };

const key = await crypto.subtle.importKey(
  "raw",
  Uint8Array.from(atob(SECRET), c => c.charCodeAt(0)),
  algorithm,
  false,
  ["sign", "verify"]
);

await crypto.subtle.verify(
  algorithm.name,
  key,
  Uint8Array.from(atob(signature), c => c.charCodeAt(0)),
  new TextEncoder().encode(message)
);

Failed Events

If your server is unavailable or returns a non-success response code, we'll retry the event a few times before marking it as failed. If you server does not return a successful response after 3 days, we'll automatically disable the webhook and send you an email to let you know. You can reenable the webhook in the Organisation Webhooks section once your server is up and running again.