FlazzPay
Webhooks

Verifying webhook signatures

Check that a webhook really comes from FlazzPay, with PHP, Node and Go examples.

FlazzPay signs every webhook with your business's webhook secret (whsec_…), created in the dashboard under Developers › Webhooks. Verify the signature before you trust the body.

Every event is described, with its body and headers, in the API reference under Webhooks.

Steps

  1. Read the raw body before you parse it. Do not re-serialize the JSON: the signature covers the exact bytes.
  2. Read X-FlazzPay-Timestamp and X-FlazzPay-Signature (header names are case-insensitive).
  3. Reject the request if the timestamp is more than five minutes from your clock.
  4. Compute hex(HMAC_SHA256(secret, timestamp + "\n" + "POST" + "\n" + path_with_query + "\n" + hex(SHA256(raw_body)))). path_with_query is the path and query of the URL you registered, for example /hooks/flazzpay, without the host.
  5. Compare it with the signature in constant time.
  6. Answer with a 2xx within 10 seconds. Anything else is retried.

Only the timestamp, method, path and body are signed. The X-FlazzPay-Event-Id and X-FlazzPay-Event-Type headers are not: trust the body.

Examples

// Laravel: $request->getContent() and $request->header('X-FlazzPay-Timestamp')
function flazzpay_verify(string $secret, string $pathWithQuery, string $rawBody, string $timestamp, string $signature, int $toleranceSeconds = 300): bool
{
    if (! ctype_digit($timestamp) || abs(time() - (int) $timestamp) > $toleranceSeconds) {
        return false;
    }
    $signed = $timestamp."\n"."POST"."\n".$pathWithQuery."\n".hash('sha256', $rawBody);

    return hash_equals(hash_hmac('sha256', $signed, $secret), strtolower($signature));
}

Handling events

  • Deduplicate on event_id. Delivery is at least once, so the same event can arrive twice.
  • Do not rely on order. Use created_at and the status inside data.
  • Confirm before you act on money. data is the resource as the matching GET returns it; you can fetch it again to be sure.
  • Retries. A failed delivery is retried 6 times in all, after 30 seconds, 1, 2, 5 and 10 minutes.
  • Test it. Press "Send test event" on an endpoint in the dashboard: you receive a webhook.test event signed the same way.
Copyright © 2026