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 unneccesarily. 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
- 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 quite minimal (on purpose) and not meant to be used in isolation. The benefit of the webhook is to receive a real-time update about an event occurring. Once this event is received, the integration can then call our other API endpoints to expand the information received.
Optionally, for increased security, you could choose to verify the payload which is being sent.
To verify the authenticity and prevent potential replay or man-in-the-middle attacks, our webhook provides a Signing Secret. This secret is unique for every webhook, and is combined with the payload into a hash which we will send in the Signature header.
To verify the authenticity of the webhook's payload you can create a SHA-256 hash of the payload and the secret, and compare it with hash which we have sent in the Signature header.