# Webhook signatures

Webhook event security uses a Base64-encoded HMAC-SHA256 signature generated with your webhook endpoint secret. Each notification includes a `signature` value in the headers.

- `signature` – a Base64-encoded HMAC-SHA256 digest of the raw request body, signed with your webhook endpoint secret.


Unlike v1, webhook deliveries do not include a public key in the headers. Identify the correct webhook endpoint secret using the endpoint that received the webhook.

## Verify a signature

1. Determine which endpoint received the webhook, and look up that endpoint's secret.
2. Generate a signature from the raw request body using the `generateSignature` function, which must return the Base64-encoded digest.
3. Compare your generated signature to the `signature` header value using a constant-time comparison function, for example `hash_equals` in PHP, `hmac.compare_digest` in Python, `crypto.timingSafeEqual` in Node.js, `hmac.Equal` in Go, `MessageDigest.isEqual` in Java or Kotlin, or `CryptographicOperations.FixedTimeEquals` in C#. Do not use `==` or `.equals()`.
4. If verification fails, retry with the previous secret before rejecting the request, in case you are inside a rotation overlap window. The old and new secrets both stay valid during rotation.
5. Reject the request without processing it if verification fails against both secrets.


Use the raw JSON body exactly as received, with no changes. Serializers, URL encoding, or reformatting can change the byte structure and produce a different hash, causing a valid webhook to fail verification.

.sg-prompt-accordion > div > :first-child { margin-top: 0; }
    .sg-prompt-accordion .sg-prompt-chevron { display:inline-block; transition:transform .15s; }
    .sg-prompt-accordion[open] .sg-prompt-chevron { transform: rotate(90deg); }
    
▸
AI prompt to verify v2 webhook signatures
Copy
Implement Solidgate v2 webhook signature verification for my integration.

Context: Solidgate v2 webhooks carry a `signature` verification header (a base64-encoded HMAC-SHA256 of the raw body, signed with a per-endpoint secret prefixed `wsec_`), along with `solidgate-event-id`, `solidgate-event-type`, and `solidgate-event-occurred-at` headers. The `event_id`, `event_type`, `occurred_at`, and `data` values also appear in the JSON body. Each webhook endpoint I registered has its own secret. There is no public key or endpoint identifier in the request itself, so the receiving URL tells me which stored secret to use.

Algorithm to implement:

1. Look up the secret (`wsec_...`) I stored for the specific endpoint URL that received this request.
2. Read the raw request body as bytes, before any JSON parsing or reserialization. The exact byte sequence affects the hash.
3. Compute HMAC-SHA256 of the raw body using that secret.
4. Base64-encode the raw digest bytes directly. There is no hex step. This differs from Solidgate v1, which hex-encodes first, so do not reuse v1 code here.
5. Compare the result to the `signature` header using a constant-time comparison. Use `hash_equals` in PHP, `hmac.compare_digest` in Python, `crypto.timingSafeEqual` in Node.js, `hmac.Equal` in Go, `MessageDigest.isEqual` in Java or Kotlin, or `CryptographicOperations.FixedTimeEquals` in C#. Do not use `==` or `.equals()`.
6. If verification fails, retry with my previous secret before rejecting, in case I am inside a rotation overlap window. Old and new secrets both stay valid during rotation.
7. Reject the request without processing it if verification fails against both secrets.


Also implement:

- Idempotency: deduplicate using `event_id` from the verified body. Store processed event IDs for at least one week (7 days) and skip duplicates seen within that window. The `solidgate-event-*` headers are not signed, so use them only for a quick check before parsing the body.
- Delivery order: do not assume ordering. Delivery order is not guaranteed, so the same event can arrive more than once and out of sequence.
- Ordering (if needed): if my integration needs to apply events in the correct order, sequence them using `occurred_at` from the verified body on a best-effort basis. This field reflects when the event occurred, not when it was delivered, so treat it as a hint rather than a guarantee.
- Fast response: verify the signature, durably enqueue the payload, then return a 200 status immediately. Process the queued payload asynchronously in a background worker rather than running business logic inside the request handler.


After generating the code, list each requirement above (secret lookup, signature algorithm, rotation fallback, idempotency, ordering, fast response) and state how the implementation satisfies it. If any requirement is not addressed, say so explicitly instead of omitting it.

Write this in my language and framework. Ask me which one if it is not clear from my codebase, and match my project's existing conventions for reading raw request bodies and structuring webhook handlers.

## Delivery headers

Every v2 webhook delivery includes the following headers.

Header
Type
Description
Example
signature
string
Base64-encoded HMAC-SHA256 of the raw request body, signed with your webhook endpoint secret.
MjNiYW...
solidgate-event-id
string
Unique ID for the event. Use it for a quick check before you parse the body. To deduplicate, use 
event_id
from the body.
3f1c8a52-0b6d-4d3e-9c2a-1e8b7f4a90d1
solidgate-event-occurred-at
string
(date-time)
Date and time when the event occurred. To order events, use 
occurred_at
from the body.
2026-04-03T16:18:40.000000Z
solidgate-event-type
string
The type of event that occurred.
SUBSCRIPTION_CREATED
## Delivery payload

Every v2 webhook payload includes the following fields.

Field
Type
Description
Example
event_id
string
Unique ID for the event. Use it to deduplicate deliveries.
3f1c8a52-0b6d-4d3e-9c2a-1e8b7f4a90d1
event_type
string
The type of event that occurred.
SUBSCRIPTION_CREATED
occurred_at
string
(date-time)
Date and time when the event occurred. Use it to order events chronologically.
2026-04-03T16:18:40.000000Z
data
object
The event payload. Structure depends on 
event_type
.
—
The same `event_id`, `event_type`, and `occurred_at` values are also sent as the `solidgate-event-id`, `solidgate-event-type`, and `solidgate-event-occurred-at` headers. The headers are not signed. Use them for a quick check, for example, to skip an event type you do not handle. For processing, use the values from the body.

## Best practices

- **Reduce replay risk**: Check the `occurred_at` field in the payload against the current time, and reject deliveries with an implausibly old timestamp. Choose a cutoff wide enough to tolerate retries and delivery delays. This check reduces risk but does not fully prevent replay, since a valid signed payload can still be replayed within the accepted window. Use `event_id` deduplication as the primary control against duplicate processing.
- **Process asynchronously**: Return a `200 OK` response immediately after signature verification, then handle the payload in a background queue. This avoids timeout failures during traffic spikes.
- **Ensure idempotency**: Delivery order is not guaranteed, and the same event may arrive more than once with the same `event_id`. Store processed event IDs for at least one week, and skip any duplicate. This deduplication is separate from the [`Idempotency-Key` header](https://api-docs.solidgate.com/api/v2/idempotent-requests) used for request retries.


For help, contact us.