Overview

Webhooks allow your application to receive real-time notifications about events occurring within the Loloyal platform. This document provides an overview of how to set up and use webhooks with Loloyal.

Subscribing to webhooks

Manage webhook subscriptions through the Webhook API - view existing ones, create new subscriptions, or unsubscribe from events.

Verifying requests

The webhooks we deliver have a X-Loloyal-Hmac-Sha256 header, which is a base64 encoded sha256 HMAC of the raw JSON request body and the relevant private API key.

Example code to verify a webhook:

def verify_webhook_signature():
    # Get required headers
    received_signature = request.headers.get('X-Loloyal-Hmac-Sha256')
    triggered_at = request.headers.get('X-Loloyal-Triggered-At')

    # Get raw body
    request_body = request.get_data(as_text=True)

    # Concatenate body and triggered_at
    message = request_body + triggered_at

    # Calculate HMAC-SHA256
    expected_signature = hmac.new(
        b'your_private_api_key',  # Replace with your actual webhook secret
        message.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    # Compare signatures
    return hmac.compare_digest(expected_signature, received_signature)

Response to webhooks

Your app must confirm receipt of the webhook event by returning a 200 status code.

If the response status falls outside the 2xx range, or if no response is received, the delivery will be considered failed.

Webhook retries

Failed webhook events are retried using exponential backoff until either a successful response is received or the webhook subscription is automatically removed after 10 failed attempts.