> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bullring.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook verification

> Verify Convoy Bullring webhook signatures with the endpoint secret.

THE RECEIPT

Bullring delivers webhooks through Convoy. Every request includes:

```http theme={null}
X-BULLRING-SIGNATURE: t=<timestamp>,v1=<hash>
```

The endpoint secret is returned by the dashboard when the webhook endpoint is created. Store it securely.

## Verification algorithm

1. Read `X-BULLRING-SIGNATURE`.
2. Split the header by commas.
3. Extract the `t` timestamp and `v1` hash.
4. Serialize the request payload exactly as received by your webhook framework.
5. Compute:

```text theme={null}
Base64(HMAC-SHA256(secret, `${timestamp},${payload}`))
```

6. Compare the generated value with `v1` using a constant-time comparison.
7. Reject stale timestamps according to your replay window.
8. Return a `2xx` only after verification and durable acceptance.

Example header:

```text theme={null}
X-BULLRING-SIGNATURE: t=1492774577,v1=ansdoj213e98jqd928u3eudh239eu2j9d2jd8ejd238eu23ei2d9j23e8u23eue3
```

## Node.js example

```javascript theme={null}
import { createHmac, timingSafeEqual } from "crypto";

function verifyBullringWebhook(rawPayload, signatureHeader, secret) {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((part) => part.split("="))
  );

  const timestamp = parts.t;
  const receivedHash = parts.v1;
  const signedPayload = `${timestamp},${rawPayload}`;

  const expectedHash = createHmac("sha256", secret)
    .update(signedPayload)
    .digest("base64");

  const received = Buffer.from(receivedHash, "utf8");
  const expected = Buffer.from(expectedHash, "utf8");

  return (
    received.length === expected.length &&
    timingSafeEqual(received, expected)
  );
}
```

Use the raw request body when possible. If your framework parses the body first, reproduce the exact serialization used by the request before calculating the HMAC.

## Delivery behavior

* Convoy retries deliveries that do not receive a `2xx` response.
* Deduplicate events using the event ID in the payload when available.
* Do not process the event before signature verification.
* Do not log the webhook secret or full signature header.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.