Skip to main content

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 a 200 status code within 5 seconds. Do any heavy processing asynchronously after responding.

2. Handle duplicates

Webhooks may be delivered more than once. Use the evt_* 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.