Home / / Web hooks

Web hooks

2040 views 2 min , 15 sec read

Web hooks are a developer tool that allows you to integrate the BYDA referral service into your own business applications.

To access the web hook options, you first need to enable developer tools for your account.

How web hooks work

Using web hooks you can choose to be notified of certain events that occur within the BYDA referral service. For example, your might have an application that is notified every time a new enquiry is lodged by a member of your team to trigger a response collation workflow.

Each time the event occurs, SmarterWX Sentinel makes a call to your web service including information about the event (for example, details of the enquiry that has been lodged).

There are different events available depending on your role. All users have access to personal events. Asset owning members also have access to additional organisation events.

  • Enquiry create (personal) – triggers each time you lodge an enquiry.
  • Response create (personal) – triggers each time a response is received for your enquiry.
  • Referral create (member) – triggers each time a referral is created for your organisation.
  • Response create (member) – triggers each time a response is returned by your organisation.

Subscribing to a web hook

To subscribe to a web hook, go the Developer tools -> Web hook subscriptions and select your chosen event type to open the subscription details panel.

Web hook subscription details form

  • Web service URL: the URL that will be called with an HTTP POST request for each event.
  • Signing secret key: a secret used to add a digital signature to every request. Use the Generate key button to create a random secret to use for signing your requests. Alternatively, you can provide your own value.
  • Custom HTTP headers: an optional list of fixed HTTP headers to include with the requests (typically used for firewalls).
Requirements
  • The web service must be HTTPS using port 443 with a valid certificate.
  • The web server must be reachable from the SmarterWX cloud.
  • The web server must support GET / to confirm the reachability of the server.

Organisation or member web hooks are subscribed once per organisation. If someone else in your organisation has already created a web hook subscription for a member event, you cannot create a second subscription.

Verifying the digital signature

Each webhook event includes a stringified JSON payload in the request body. To verify that the event originated from SmarterWX Sentinel, you can compare the X-SWX-Signature HTTP header that includes an HMAC digest of the request body, generated using an SHA-256 hash function using your secret signing key.

This example NodeJS code shows how the signature can be generated for verification purposes:

import { createHmac } from 'crypto';
const signature = createHmac('sha256', secret).update(body).digest('hex');

const receivedSignature = headers['X-SWX-Signature'];

const isVerified = `sha256=${signature}` === receivedSignature;

Error handling

The web service is responsible for returning a success message to acknowledge receipt of each web hook event. The response must include an HTTP 2XX status code and must return within 3 seconds. A response with a non-2XX status code or a request that times out after 3 seconds will be assumed to have failed and SmarterWX Sentinel will keep trying to deliver the event.

If a call to your web service fails, an exponential back-off algorithm is used to gradually increase the time between successive retries. If there is no success after 12 attempts to deliver a message, it will be classed as permanently failed and we will stop trying. You can view the status of all event notifications sent to your web services through the Web hook notifications page in the web application. From here you can also restart sending of a permanently failed message.

Due to the vagaries of the internet, a request may time out even though your web server believes it has successfully responded. As such, your service must be able to handle duplicate messages. You can de-duplicate requests by comparing the UUID that is included with every message.

Firewalls

If your firewall requires details of the IP address range used to send web hook events, please whitelist the IP address 52.65.109.17