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
- Read the raw body before you parse it. Do not re-serialize the JSON: the signature covers the exact bytes.
- Read
X-FlazzPay-TimestampandX-FlazzPay-Signature(header names are case-insensitive). - Reject the request if the timestamp is more than five minutes from your clock.
- Compute
hex(HMAC_SHA256(secret, timestamp + "\n" + "POST" + "\n" + path_with_query + "\n" + hex(SHA256(raw_body)))).path_with_queryis the path and query of the URL you registered, for example/hooks/flazzpay, without the host. - Compare it with the signature in constant time.
- Answer with a
2xxwithin 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));
}
// Express: app.post('/hooks/flazzpay', express.raw({ type: 'application/json' }), ...)
// req.body is a Buffer and req.get('X-FlazzPay-Signature') is the signature.
const crypto = require('node:crypto')
function verifyFlazzPay(secret, pathWithQuery, rawBody, timestamp, signature, toleranceSeconds = 300) {
if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) return false
const bodyHash = crypto.createHash('sha256').update(rawBody).digest('hex')
const expected = crypto.createHmac('sha256', secret).update(`${timestamp}\nPOST\n${pathWithQuery}\n${bodyHash}`).digest()
const received = Buffer.from(String(signature).toLowerCase(), 'hex')
return received.length === expected.length && crypto.timingSafeEqual(received, expected)
}
// body, _ := io.ReadAll(r.Body); r.Header.Get("X-FlazzPay-Signature")
func VerifyFlazzPay(secret, pathWithQuery string, rawBody []byte, timestamp, signature string, tolerance time.Duration) bool {
ts, err := strconv.ParseInt(timestamp, 10, 64)
if err != nil || time.Since(time.Unix(ts, 0)).Abs() > tolerance {
return false
}
bodyHash := sha256.Sum256(rawBody)
mac := hmac.New(sha256.New, []byte(secret))
mac.Write([]byte(timestamp + "\nPOST\n" + pathWithQuery + "\n" + hex.EncodeToString(bodyHash[:])))
received, err := hex.DecodeString(strings.ToLower(signature))
return err == nil && hmac.Equal(mac.Sum(nil), received)
}
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_atand the status insidedata. - Confirm before you act on money.
datais the resource as the matchingGETreturns 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.testevent signed the same way.
