Webhooks
Webhooks let you receive real-timepayment.succeeded notifications whenever a buyer pays for any of your resources — endpoints, products, components, or agent endpoints.
Plan Requirement: Webhooks are available on Pro and Business plans only. Free plan accounts receive a 403 response.
How It Works
Webhooks are account-level (seller-level), not per-resource. You register one webhook URL and it receives events for all resources you own.- 💰 Payment Happens — Buyer pays for any of your resources
- 📡 Webhook Fires — Signed POST request to your URL
- ✅ You Act — Fulfill order, grant access, log it
Setup via Dashboard
- Go to Dashboard → Webhooks
- Click Create Webhook
- Enter your HTTPS endpoint URL
- A signing secret is generated automatically — copy and store it securely
Event: payment.succeeded
Every webhook delivery is a POST request with this JSON body:
Verifying Signatures
Studio seller webhooks are HMAC-signed. Current deliveries include:X-X402-Signature— HMAC-SHA256 hex digestX-X402-Timestamp— Unix timestamp for the deliveryX-X402-Event— event type for routing/loggingX-X402-Event-Id— stable event id for idempotency/replay protection
- payload:
timestamp.rawBody - algorithm:
HMAC-SHA256 - secret: webhook
signing_secret
Node.js
Python
Backward Compatibility
Some older receivers still accept raw-secret headers like:x-x402layer-secretx-x402-secretAuthorization: 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-secretand the app verifies it withX402_WEBHOOK_SECRET
Coverage Matrix
Best Practices
- 🔐 Always verify signed headers first — Never trust unverified payloads.
- ⚡ Respond quickly (< 5s) — Process asynchronously and return
200immediately. Queue heavy work. - 🔄 Handle duplicates — Use the event
idfor 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
401but a manual POST with the stored secret works, the receiver likely only supports legacy raw-secret auth while Studio is sending signed webhooks.
