Webhooks
Webhooks notify your system in real-time when payment events occur. Instead of polling the API, register a URL and we’ll send HTTP POST requests with event data as payments are confirmed, expire, or fail.Event Types
Webhook Payload
Every webhook has the same envelope structure:payment_intent.confirmed
payment_intent.expired
Handling Webhooks
1. Return 200 quickly
Your endpoint must return a200 status code within 5 seconds. Do any heavy processing asynchronously after responding.
2. Handle duplicates
Webhooks may be delivered more than once. Use theevt_* ID to deduplicate:
3. Verify signatures
Every webhook includes a signature header for verification. See Webhook Security for details.Retry Policy
If your endpoint returns a non-2xx status code or doesn’t respond within 5 seconds, we retry with exponential backoff:
After 6 failed attempts, the webhook is marked as failed. You can view and manually retry failed webhooks in the dashboard.
Testing Webhooks
In sandbox mode (sk_test_* keys), you can trigger test webhook events from the dashboard to verify your endpoint is working correctly without sending real USDC.
