Webhooks
Webhooks allow you to receive real-time notifications when events occur in your ZKP2P Pay integration.
How Webhooks Work
When an event occurs (like a payment being fulfilled), ZKP2P Pay sends an HTTP POST request to your configured webhook URL with details about the event.
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Payment │ │ ZKP2P Pay │ │ Your Server │
│ Event │────>│ Webhook │────>│ Endpoint │
│ │ │ Delivery │ │ │
└─────────────┘ └─────────────┘ └─────────────┘
Available Events
| Event Type | Description |
|---|---|
order.created | Order created and intent signaled on-chain |
order.payment_sent | User marked payment as sent |
order.fulfilled | Payment verified and USDC transferred |
order.failed | Payment verification or fulfillment failed |
order.expired | Order expired before completion |
session.started | Checkout session started by user |
session.completed | Checkout session completed successfully |
session.abandoned | User abandoned the checkout |
See Events for detailed information on each event.
Webhook Security
All webhooks are signed using HMAC-SHA256. You should verify the signature before processing any webhook to ensure it came from ZKP2P Pay.
Headers included with each webhook:
| Header | Description |
|---|---|
X-Webhook-Id | Unique event ID (for idempotency) |
X-Webhook-Timestamp | Unix timestamp when the webhook was sent |
X-Webhook-Signature | HMAC-SHA256 signature of the payload |
See Verification for implementation details.
Retry Policy
If your endpoint doesn't respond with a 2xx status code, ZKP2P Pay will retry the webhook with exponential backoff:
| Attempt | Delay |
|---|---|
| 1 | Immediate |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 8 hours |
| 7 | 24 hours |
| 8 | Final attempt |
After 8 failed attempts, the webhook is marked as failed.
Quick Start
- Set up a webhook via the API
- Handle events in your endpoint
- Verify signatures for security
- Follow best practices for reliability