The Signature Header
When Blink sends a webhook to your server, it includes the following headers:Blink-Signature: The cryptographic signature of the payload (e.g.,v1=a1b2c3d4...)Blink-Timestamp: The unix timestamp (in seconds) when the event was dispatched.Blink-Event: The name of the event (e.g.,order.paid).Blink-Event-Id: The unique identifier for the webhook event (e.g.,evt_9b1deb4d...), matching the top-levelidfield in the JSON body. Use this value for idempotency / deduplication.
How to Verify the Signature
The easiest and most secure way to verify webhooks is by using the official Blink SDKs. The SDKs provide a single helper functionconstructEvent that automatically verifies the signature, prevents replay attacks, and parses the JSON payload for you.
Example: Next.js (App Router)
Example: Python (FastAPI)
Replay Attacks
As a best practice to prevent replay attacks, the SDK automatically checks that theBlink-Timestamp is within a reasonable tolerance (5 minutes) of your server’s current time. If it is older, it throws a ToleranceError.
Test vs Live Webhooks
Manual Verification (Without SDK)
If you are using a language without an official Blink SDK, you can verify the signature manually. Blink uses HMAC with SHA-256 to sign webhook payloads. Follow these steps:- Extract the timestamp and signature from the headers.
- Prepare the signed payload string by concatenating the timestamp, a dot (
.), and the raw JSON request body:${timestamp}.${rawBody}. - Compute the expected HMAC signature using SHA-256, your signing secret, and the signed payload string.
- Compare the signatures. If your computed signature matches the one in the
Blink-Signatureheader (stripping thev1=prefix), the webhook is valid!