Skip to main content

Best practices

Signature Verification​

To ensure data integrity and verify authenticity, the payload (an array of data) intended for the webhook is serialized into JSON format. Subsequently, an HMAC-SHA256 (Hash-based Message Authentication Code using the SHA-256 hashing algorithm) is computed using the serialized payload and a secret key. This HMAC is then included in the HTTP request as a Signature header.

  1. Retrieve the payload and Signature header from the HTTP request.
  2. Recompute the HMAC-SHA256 using the received payload and the secret key.
  3. Compare the computed HMAC with the value of the Signature header.
  4. If the two values match, the payload can be trusted as originating from a verified source. If they do not match, the payload may have been tampered with or originated from an untrusted source.

The secret key used for computing the HMAC is generated for each new webhook and can be viewed after the webhook is created. This enables webhook integrators to securely configure and validate incoming webhook requests.

This verification process ensures that the transmitted data remains unchanged and can be safely processed by the recipient webhook.

Example
<?php

// Define the secret key
$secret = 'my_secret';

// Get the signature from the request headers
$signatureHeader = $_SERVER['HTTP_SIGNATURE'] ?? null;

// Get the raw POST data
$rawData = @file_get_contents('php://input');
$payload = json_decode($rawData, true);

// Calculate the expected signature
$expectedSignature = hash_hmac('sha256', json_encode($payload), $secret);

// Verify the signature
if ($signatureHeader !== $expectedSignature) {
    // Return a 400 Bad Request response
    http_response_code(400);
    echo 'Invalid signature';
    exit;
}

// Handle your event here
echo 'Event handled';

Only listen to event types your integration requires​

Configure your webhook endpoints to receive only the event types essential for your integration. Listening to unnecessary events or all events can strain your server, which is not recommended.

Handle events asynchronously​

Configure your handler to process incoming events using an asynchronous queue. Processing events synchronously can lead to scalability issues. A large spike in webhook deliveries might overwhelm your endpoint hosts.

Asynchronous queues help manage concurrent events at a rate your system can handle.

Handle duplicate events​

Webhook endpoints might occasionally receive the same event more than once. You can guard against duplicated event receipts by logging the event IDs you've processed, and then not processing already-logged events.

On this page