Skip to main content

Webhooks

Webhooks let you receive real-time payment.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.
  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
From the Webhooks dashboard you can also toggle webhooks on/off, rotate the signing secret, delete webhooks, and view recent delivery logs.

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 body
  • X-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 200 immediately. Queue heavy work.
  • 🔄 Handle duplicates — Use the event id for idempotency.
  • 🔑 Rotate secrets periodically — Use Dashboard → Webhooks → Rotate Secret.

Webhook API Reference