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
Every delivery includes two headers for HMAC verification:X-X402-Signature— HMAC-SHA256 hex digest of the raw bodyX-X402-Timestamp— Unix timestamp of when the event was sent
Node.js
Python
Coverage Matrix
Best Practices
- 🔐 Always verify signatures — Never trust unverified payloads.
- ⚡ Respond quickly (< 5s) — Process asynchronously and return
200immediately. Queue heavy work. - 🔄 Handle duplicates — Use the event
idfor idempotency. - 🔑 Rotate secrets periodically — Use Dashboard → Webhooks → Rotate Secret.
