Using Webhooks

Webhooks are a way for developers to integrate Leave Dates with 3rd party products.

Every time a certain event occurs (for example, a new leave is requested) we will send the data to your chosen destination URL. 

The benefits of using a webhook

Using a traditional API, you would need to constantly request (pull) data about recent updates. These requests would need to be set up to 'poll' the data on a regular basis (Ex. every 10 minutes) to check for updates, usually returning no results.

Using a webhook, you simply wait to be sent (or pushed) details about events you are interested in. Meaning you will receive the data instantly when it happens, and never have to check unnecessarily. When new events are received then this can trigger other steps in your integration, for example loading the data into the other system.

Therefore, it is a more efficient method of learning about changes to your data in Leave Dates.

Setting up a webhook

• Go to the Settings > Integrations page
• Click Add Endpoint under Webhooks
  • This is the destination where we will send events
• Enter the URL of the destination where we should send the events
  • If you're new to working with webhooks, a good place to start will be https://webhook.site/ where you can start sending Leave Dates events and understanding the data format.
• Select the types of event to receive. Currently, we support:
  • Leave requested
  • Leave approved
  • Leave rejected
  • Leave cancelled
• Click Create
• A new row will be added to the table showing the created webhook

Testing webhooks

• Click the eye icon in the row of your webhook.
• A new window will open showing the previous webhook events. 
• Each event can be clicked to show further information about the request and response.
• If no events have been generated, either request some leave or create a test event using the SEND TEST EVENT section in the top right.
• Each event shows the status (Success or Error)

Webhook and event status

• The status of each event is displayed next to the event in the list
• If an event has an error, the webhook will be retried up to 5 times.
• After 5 failed events in a row, the webhook will be marked as Broken (in the Settings > Integrations page) and no further events will be sent.
  • To restart a broken webhook, simply send a test event to it. If this event is successful then the webhook will change to Active and events will continue to be sent.

Integrating the webhook

The data sent in the webhook is intentionally minimal and not meant to be used in isolation. The purpose of the webhook is to provide a real-time notification that an event occurred. After receiving the event, your integration can call our other API endpoints to fetch additional details.

Security (optional)

For increased security, you can verify that webhook requests are authentic and untampered.

To help prevent replay and man-in-the-middle attacks, each webhook is associated with a Signing Secret. We compute a signature by combining this secret with the webhook request payload and include the result in the Signature  HTTP header.

How to verify the signature

1. Read the raw HTTP request body exactly as received

Do not parse, modify, or re-stringify the body (e.g., JSON.parse + JSON.stringify) before computing the HMAC

2. Compute an HMAC-SHA256 over the raw request body using your Signing Secret as the key
3. Compare your computed HMAC to the value in the Signature header

Use a constant-time comparison function to avoid timing attacks

4. If the signatures match, the request can be treated as authentic.