Webhook Overview

What are Webhooks

Webhooks are a mechanism that allows an application to send real-time data to another application whenever a specific event occurs. Instead of constantly polling an API to check for updates, webhooks enable a more efficient way of receiving data by pushing it to a specified endpoint when the event happens.

Key Characteristics of Webhooks

• Event-Driven: Webhooks are triggered by specific events, such as a new user registration, a file upload, or a payment confirmation.
• Push-Based: Instead of the receiving application polling for updates, the source application pushes data to the webhook endpoint.
• Real-Time: Webhooks provide near-instantaneous updates, allowing for real-time integration between systems.

How Webhooks Work

1. Event Triggered: An event occurs in the application (e.g., a new booking is created, a customer is deleted, an activity is registered).
2. Notification Sent: The application detects the event and sends an HTTP request (POST request) to a pre-configured URL (Server URL).
3. Data Delivered: The payload of the HTTP request contains information about the event in JSON format.
4. Endpoint Receives Data: The server at the webhook endpoint (Server URL) receives the data and processes it accordingly.

TIMIFY Webhooks

In order to subscribe for any Webhook, your App must align and have the minimum required Application scope access.

You can find in the following table the reference for each Webhook and equivalent App Scope(s):

How to Create Webhooks

To create a webhook, you need to first have an App. Then, by accessing the app details, you will see a tab called "Webhooks Subscriptions". From there, you can create your first webhook subscription:

Note that you can create multiple webhook subscriptions, each with individual Server URL and webhook scope, allowing to separate the incoming data to your servers and integration for a better orchestration and data processing.

Securing Webhooks with Custom Headers

To help secure your webhook endpoint, you can enable the “Include header name” option when setting up your webhook. This allows you to define a custom HTTP header name and assign it a secret key value.

When enabled:
• The specified header and secret will be included in every webhook request sent to your server.
• You can then validate this header and secret on your end to verify that incoming requests originate from TIMIFY.

This mechanism adds an extra layer of security by enabling you to filter out unauthorized requests and ensure that only trusted webhook calls are processed.