# Solidgate Webhooks

## When to Use This Skill

* How do I receive Solidgate webhooks?
* How do I verify Solidgate webhook signatures?
* How do I handle `card_gate.order.updated` or `subscription.updated.v2` events?
* Why is my Solidgate webhook signature verification failing?
* Setting up a Solidgate payment or subscription webhook handler

## Verification (core)

Solidgate does not use Standard Webhooks. Each request carries two headers:

* `merchant` — your webhook public key (prefix `wh_pk_`)
* `signature` — the HMAC to check

The signature is built with an unusual double-encode: HMAC-SHA512 over
`publicKey + rawBody + publicKey` using your webhook secret key (`wh_sk_`),
then take the hex digest, then Base64-encode that hex string (you encode
the hex text, not the raw digest bytes). Use the exact raw request body — never
re-serialize the JSON, or verification fails.

Node (matches `@solidgate/node-sdk`'s internal signing):

```javascript
const crypto = require('crypto');

function verifySolidgate(rawBody, signature, publicKey, secretKey) {
  const body = Buffer.isBuffer(rawBody) ? rawBody.toString('utf8') : rawBody;
  const hex = crypto.createHmac('sha512', secretKey)
    .update(publicKey + body + publicKey)   // publicKey wraps the raw body
    .digest('hex');                          // 1) hex digest
  const expected = Buffer.from(hex).toString('base64'); // 2) base64 of the hex string
  try {
    return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  } catch {
    return false; // length mismatch = invalid
  }
}

```

Python (manual — the `solidgate-sdk` has no public webhook-verify helper):

```python
import base64, hashlib, hmac

def verify_solidgate(raw_body: bytes, signature: str, public_key: str, secret_key: str) -> bool:
    message = public_key.encode() + raw_body + public_key.encode()
    hex_digest = hmac.new(secret_key.encode(), message, hashlib.sha512).hexdigest()
    expected = base64.b64encode(hex_digest.encode()).decode()
    return hmac.compare_digest(expected, signature)

```

> For complete handlers with route wiring, event dispatch, and tests, see:
> 
> * [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/solidgate-webhooks/examples/express/)
> * [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/solidgate-webhooks/examples/nextjs/)
> * [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/solidgate-webhooks/examples/fastapi/)

## Common Event Types

The event type is delivered in the `solidgate-event-type` header (and mirrored in
the `solidgate-event-id` header for idempotency).

| Event | Description |
| --- | --- |
| `card_gate.order.updated` | Card payment order status changed (approved, declined, refunded) |
| `card_gate.chargeback.received` | A chargeback was opened on a card order |
| `card_gate.fraud_alert.received` | Fraud alert (TC40/SAFE) received for a card order |
| `card_gate.prevention_alert.received` | Prevention alert (RDR/Ethoca) received |
| `subscription.updated.v2` | Subscription state changed (the `.v2` suffix is real) |
| `alt_gate.order.updated` | Alternative payment method order status changed |
| `alt_gate.paypal_dispute.received` | A PayPal dispute was opened |

> For the full event reference, see [Solidgate Webhooks](https://docs.solidgate.com/payments/integrate/webhooks/).

## Environment Variables

```bash
SOLIDGATE_WEBHOOK_PUBLIC_KEY=wh_pk_xxxxx   # "merchant" header value, from Hub > Developers
SOLIDGATE_WEBHOOK_SECRET_KEY=wh_sk_xxxxx   # webhook secret key, used to compute the HMAC

```

Webhook keys (`wh_pk_` / `wh_sk_`) are a separate pair from your API keys —
they are used exclusively for validating webhook payloads.

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 solidgate --path /webhooks/solidgate

```

## Delivery & Retries

Return a `2xx` within 30 seconds. Solidgate retries up to 8 times with
backoff at 15m, 30m, 1h, 2h, 4h, 8h, 16h, 24h. Use the `solidgate-event-id`
header to deduplicate retried deliveries.

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/solidgate-webhooks/references/overview.md) - Solidgate webhook concepts and events
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/solidgate-webhooks/references/setup.md) - Hub configuration and keys
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/solidgate-webhooks/references/verification.md) - Signature verification details and gotchas