​

Webhooks

Plan Requirement: Webhooks are available on Pro and Business plans only. Free plan accounts receive a 403 response.

​

How It Works

1. 💰 Payment Happens — Buyer pays for any of your resources
2. 📡 Webhook Fires — Signed POST request to your URL
3. ✅ You Act — Fulfill order, grant access, log it

​

Setup via Dashboard

1. Go to Dashboard → Webhooks
2. Click Create Webhook
3. Enter your HTTPS endpoint URL
4. A signing secret is generated automatically — copy and store it securely

​

Event: payment.succeeded

{
  "id": "evt_abc123",
  "event": "payment.succeeded",
  "timestamp": "2026-02-26T19:30:00Z",
  "data": {
    "source": "endpoint",
    "source_id": "ep_xyz789",
    "source_slug": "my-api",
    "amount": "1.00",
    "currency": "USDC",
    "tx_hash": "0xabc...def",
    "payer_wallet": "0x1234...5678",
    "network": "base",
    "status": "settled"
  }
}

​

Verifying Signatures

• X-X402-Signature — HMAC-SHA256 hex digest
• X-X402-Timestamp — Unix timestamp for the delivery
• X-X402-Event — event type for routing/logging
• X-X402-Event-Id — stable event id for idempotency/replay protection

• payload: timestamp.rawBody
• algorithm: HMAC-SHA256
• secret: webhook signing_secret

​

Node.js

const crypto = require('crypto');

function verifyWebhook(rawBody, signature, timestamp, secret) {
  const payload = `${timestamp}.${rawBody}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

​

Python

import hmac, hashlib

def verify_webhook(raw_body: bytes, signature: str, timestamp: str, secret: str) -> bool:
    payload = timestamp.encode() + b"." + raw_body
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

​

Backward Compatibility

• x-x402layer-secret
• x-x402-secret
• Authorization: Bearer <secret>

​

Two Secret Hops

​

1) Studio → your webhook receiver

• secret: webhook signing_secret
• auth model: HMAC verification using the signed headers above

​

2) Your receiver → your app settlement route

• secret: your own app-internal shared secret
• example: a worker sends x-x402-secret and the app verifies it with X402_WEBHOOK_SECRET

​

Coverage Matrix

​

Best Practices

• 🔐 Always verify signed headers first — Never trust unverified payloads.
• ⚡ Respond quickly (< 5s) — Process asynchronously and return 200 immediately. Queue heavy work.
• 🔄 Handle duplicates — Use the event id for idempotency.
• 🔑 Rotate secrets carefully — If deliveries suddenly start returning 401, first check whether the webhook signing secret rotated or drifted. Update the receiver before discarding the old value.
• 🧾 Log headers, not secrets — Log signature/timestamp/event/event-id presence for debugging, but never log the secret itself.
• 🛠️ Know the common failure mode — If Studio deliveries 401 but a manual POST with the stored secret works, the receiver likely only supports legacy raw-secret auth while Studio is sending signed webhooks.

​

Webhook API Reference