Solidgate Webhooks Skill

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):

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):

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/
• examples/nextjs/
• 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).

For the full event reference, see Solidgate Webhooks.

Environment Variables

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

# 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 - Solidgate webhook concepts and events
• references/setup.md - Hub configuration and keys
• references/verification.md - Signature verification details and gotchas