Documentation Index

Fetch the complete documentation index at: https://docs.x402layer.cc/llms.txt

Use this file to discover all available pages before exploring further.

​

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 of the raw body
• X-X402-Timestamp — Unix timestamp of when the event was sent

​

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 = f"{timestamp}.{raw_body.decode()}"
    expected = hmac.new(
        secret.encode(), payload.encode(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

​

Coverage Matrix

​

Best Practices

• 🔐 Always verify signatures — 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 periodically — Use Dashboard → Webhooks → Rotate Secret.

​

Webhook API Reference