Webhooks

A webhook allows our system to send event notifications to your application automatically. You provide a URL where you want to receive updates, and our system will send event data as a JSON payload with POST method whenever something happens.

Adding a Webhook

To add a webhook, go to the API Addon and provide the URL of your server. After saving, a secret key will be generated for security purposes.

Deleting or Deactivating a Webhook

You can delete or deactivate a webhook if you no longer wish to receive events. Deactivating allows you to pause notifications without deleting the webhook.

Event Management

Choose specific events (e.g., client created, match updated) that trigger your webhook. You can manage these in the Webhook Events in Webhook actions by selecting or deselecting event types. No events chosen by default.

Supported Events:

These events can be configured to trigger the webhook based on your business requirements.

Webhook Examples:

{
    "event": "client_created",
    "payload": {
        "id": 1
    }
}

{
    "event": "client_updated",
    "payload": {
        "id": 1,
        "is_archived": True
    }
}

{
    "event": "client_profile_updated",
    "payload": {
        "id": 1,
        "prof_1": "1992-08-12"
    }
}

{
    "event": "client_preferences_updated",
    "payload": {
        "id": 1,
        "pref_1": "1992-08-12"
    }
}

{
    "event": "client_preferences_updated",
    "payload": {
        "id": 1,
        "pref_235": {
            "start": "2023-04-13",
            "end": "2024-10-26"
        }
    }
}

{
    "event": "match_added",
    "payload": {
        "id": 482,
        "client": {"id": 2},
        "match": {"id": 1},
        "group": {
            "id": 1,
            "name": "Group 1"
        }
    }
}

{
    "event": "match_updated",
    "payload": {
        "id": 482,
        "status": {
            "id": 3,
            "name": "Prepared for date "
        }
    }
}

Verifying Your Webhook

When you add a webhook, it is not active by default. To activate it, click on the Verify button in webhook actions. Our system sends a special event called "verification" to your webhook URL. This event contains a "challenge" string that your server must respond to via JSON {"challenge": <code>}, confirming that the webhook is correctly set up.

If you make any changes to the webhook URL, the webhook will be automatically deactivated, and you will need to verify it again.

Example verification payload:

{
    "event": "verification",
    "challenge": "FtvnJ1ULgKRNsqEg"
}

Webhook Response:

Your endpoint must quickly return a successful status code 200 before any complex logic that could cause a timeout.

Securing Webhook Data with X-Signature and Timestamp

Each webhook request includes an X-Signature and X-Timestamp header to help you verify the authenticity of the request and ensure that it has not been tampered with. The signature is generated using a combination of the webhook secret key, the timestamp, and the payload.

Signature Generation Process:

Verifying the Signature on Your Side:

Python Example for Verifying Signature:

import hmac
import hashlib

def verify_webhook_signature(payload, received_signature, received_timestamp, webhook_secret):
    message = f'{received_timestamp}.{payload}'  # Recreate the message with the timestamp and payload

    # Recompute the signature using HMAC SHA-256
    computed_signature = hmac.new(
        webhook_secret.encode(),
        message.encode(),
        hashlib.sha256
    ).hexdigest()

    # Compare the received signature with the computed one
    return hmac.compare_digest(computed_signature, received_signature)

Retry Mechanism

If a webhook request fails, we will retry delivery up to 5 times with the following intervals:

Cancellation Mechanism

For each failed webhook, the system checks how many requests have been made in the past 24 hours. Specifically, it counts:

If more than 40% of the webhook requests in the last 24 hours have failed after 3 or more retry attempts, the system will:

Webhooks Usage

Check the Webhooks Usage for a history of webhook events, including their delivery status (accepted, failed, retry, canceled), sent date, retry count, payload.

If a webhook has the status failed, retry, or canceled, you also have the option to manually resend the webhook. This allows you to attempt delivery again without waiting for the automated retry process.