# Webhook signatures

## Webhook validation

Webhook event security works like API authentication. Each notification includes `merchant` and `signature` values in the headers.

- **`merchant`:** your webhook Public key (`wh_pk_`).
- **`signature`:** an HMAC-SHA512 hash of the request body, signed with your webhook Secret key.


**Verify a signature**

Retrieve the 
merchant
value from the request headers and confirm it matches one of your webhook Public keys.
Look up the Secret key paired with that Public key.
Generate a signature from the raw request body using the same 
generateSignature
function you use for API requests.
Compare your generated signature to the 
signature
header value. Reject the request if they do not match.
> 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); }
    .sg-event-accordion > div { padding: 8px; box-sizing: border-box; }
    .sg-event-accordion .md-table-wrapper,
    .sg-event-accordion table { margin: 0; padding: 0; width: 100%; max-width: 100%; box-sizing: border-box; }
    .sg-event-accordion blockquote { margin: 8px 0 0; }
    
▸
AI prompt to verify v1 webhook signatures
Copy
Implement Solidgate v1 webhook signature verification for my integration.

Context: Solidgate signs v1 webhooks the same way it signs v1 API requests. Every v1 webhook delivery includes five headers: `merchant` (my webhook public key, prefixed `wh_pk_`), `signature` (the value to check), `solidgate-event-id` (a content-derived unique ID, for deduplication), `solidgate-event-created-at` (for replay checks and ordering), and `solidgate-event-type`.

Algorithm to implement:

1. Read the raw request body as bytes, before any JSON parsing or reserialization. The exact byte sequence affects the hash.
2. Confirm the `merchant` header matches my known webhook public key (`wh_pk_...`). Reject immediately if it does not.
3. Build this string: `publicKey + rawBody + publicKey`. The public key wraps both sides of the raw body.
4. Compute HMAC-SHA512 of that string using my webhook secret key (`wh_sk_...`).
5. Hex-encode the raw digest bytes to get a hex string.
6. Base64-encode that hex string, not the raw digest bytes. This double-encoding step is easy to miss. It is the most common cause of "signature never matches" bugs in this integration.
7. 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()`.
8. Reject the request without processing it if either check fails.


Also implement:

- Idempotency: deduplicate using the `solidgate-event-id` header. Store processed event IDs for at least one week (7 days) and skip duplicates seen within that window.
- Delivery order: do not assume ordering. Delivery order is not guaranteed. Use the `solidgate-event-created-at` header to sequence events on a best-effort basis if needed, but treat it as a hint, not a guarantee.
- Retries: Solidgate retries failed deliveries at these exact intervals after the first attempt: 15 minutes, 30 minutes, 1 hour, 2 hours, 4 hours, 8 hours, 16 hours, then 24 hours (8 attempts total, spanning about 2 days). The same event can arrive more than once because of these retries.
- Fast response: respond with a 2xx status within 30 seconds of receipt. If processing takes longer, verify the signature, durably store the event, return 2xx immediately, then process the event asynchronously in a background job or queue.


After generating the code, list each requirement above (headers, signature algorithm, idempotency, delivery order, retries, 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 v1 webhook delivery includes the following headers.

Header
Type
Description
Example
merchant
string
Your webhook public key (
wh_pk_
). Use this to look up the corresponding secret key on your server.
wh_pk_abc123
signature
string
Base64(Hex(HMAC-SHA512)) of the request body, signed with your webhook secret key.
MjNiYW...
solidgate-event-id
string
Content-derived unique ID for the event. Use this to deduplicate deliveries.
e1765cf7-70f7-4e56-8fb2-bd88744a94d1
solidgate-event-created-at
string
Date and time when the event was created in UTC. Use this to order events chronologically.
2025-06-05T12:34:56.789
solidgate-event-type
string
The type of event that occurred.
card_gate.order.updated
**Best practices**

- **Process asynchronously:** Verify the signature, durably store the event, then return a `200 OK` immediately, and 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 might arrive more than once with the same `solidgate-event-id`, including retries spanning up to 24 hours after the first attempt. Store processed event IDs for at least one week and skip any duplicate.


## Webhook events

Subscribe to event types when you create or update a webhook endpoint. Full payload contracts stay on each event page in this reference. For endpoint setup, retries, and delivery headers, see the webhooks guide.

▸
Card payments
Event type
Description
card_gate.order.updated
Real-time status changes for an 
Updated card order
.
card_gate.chargeback.received
Received dispute
notifications for a card chargeback.
card.network_token.created
Created network token
from Visa Token Service, Mastercard Digital Enablement Service, or Secure Card on File.
card.network_token.updated
Status changes for an 
Updated network token
.
card_gate.prevention_alert.received
Issuer 
Received prevention alert
for a potential card chargeback.
card_gate.fraud_alert.received
TC40 or SAFE 
Received fraud alert
from the card network.
> `card_gate.prevention_alert.received` is delivered for both card and PayPal prevention alerts. Inspect the payload to tell the two cases apart.


▸
Alternative payments
Event type
Description
alt_gate.order.updated
Status updates for an 
Updated alternative order
.
alt_gate.paypal_dispute.received
Creation and progression of a 
Received PayPal dispute
.
card_gate.prevention_alert.received
Issuer 
Received prevention alert
for a potential PayPal chargeback. The token is the same as for card prevention alerts.
alt_gate.recurring_token.cancelled
A 
Revoked recurring token
for an alternative payment method.
▸
Subscriptions
Event type
Description
subscription.updated.v2
Subscription initiation and status changes in 
Subscription updates
and the 
subscription events
guide.
▸
Taxes
Event type
Description
taxer.tax.calculated
Tax calculation results for a 
Calculated tax
transaction.
## Outgoing request IPs

Specific IP addresses are used for outbound requests from Solidgate to your systems (for example, webhooks). Allow traffic from these IPs in your firewall or security configuration to ensure uninterrupted service.

Configure your security systems to accept these IPs to prevent service interruptions. Stay informed about any changes to these IP addresses for continuous service.

IP addresses
3.74.184.6
/ 
3.121.136.242
18.156.25.95
/ 
18.157.254.13
/ 
18.157.119.243
/ 
18.184.24.146
/ 
18.192.168.222
/ 
18.195.90.222
35.157.172.91
/ 
35.165.202.104
44.224.79.149
52.10.37.135
/ 
52.88.195.65
For help, contact us.