Skip to main content
Blink securely signs all webhook events it sends to your endpoints. This ensures that the payloads you receive are actually from Blink and have not been tampered with by a third party. You should always verify webhook signatures before processing them in your application.

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-level id field 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 function constructEvent 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 the Blink-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

Security Best Practice: A cryptographically verified webhook only proves that the payload was sent by Blink. It does not prove that the customer actually paid real money!Blink sends webhooks for both Test (simulated) purchases and Live (real) purchases. An attacker could use a test card on your storefront checkout to trigger a perfectly valid, signed webhook.To avoid accidentally giving away your product for free, you must always explicitly check the is_test boolean inside event.data:
If your integration is in production, you should ignore or route separately any webhooks where event.data.is_test === true.

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:
  1. Extract the timestamp and signature from the headers.
  2. Prepare the signed payload string by concatenating the timestamp, a dot (.), and the raw JSON request body: ${timestamp}.${rawBody}.
  3. Compute the expected HMAC signature using SHA-256, your signing secret, and the signed payload string.
  4. Compare the signatures. If your computed signature matches the one in the Blink-Signature header (stripping the v1= prefix), the webhook is valid!

Example: Node.js (Express) without SDK