Webhooks

Webhooks deliver payment, order, and bridge lifecycle updates from ZKP2P Pay to your server.

Core Event Set

Event Type	Description
PAYMENT_SETTLED	Payment settled successfully
PAYMENT_FAILED	Payment failed terminally
PAYMENT_EXPIRED	Payment quote expired before settlement
PAYMENT_CANCELLED	Payment was cancelled
PAYMENT_CREATED	Payment attempt created
ORDER_CREATED	Order created
ORDER_FULFILLED	Order fully fulfilled
ORDER_CANCELLED	Order cancelled

For final merchant order state updates, treat PAYMENT_SETTLED, PAYMENT_FAILED, PAYMENT_EXPIRED, and ORDER_FULFILLED as the primary events.

Crypto Payment Events

If your payout flow includes bridge execution, also subscribe to bridge lifecycle events:

Event Type	Description
PAYMENT_BRIDGE_PENDING	Bridge transfer queued after settlement
PAYMENT_BRIDGE_SUBMITTED	Bridge transfer submitted to provider
PAYMENT_BRIDGE_COMPLETED	Bridge transfer completed
PAYMENT_BRIDGE_FAILED	Bridge transfer failed

Use these for destination-chain payout tracking. They are additive to the core payment/order events.

Security Headers

Header	Description
X-Webhook-Id	Unique delivery event id
X-Webhook-Timestamp	Unix timestamp
X-Webhook-Signature	HMAC-SHA256 signature

See Verification for signature handling.

Retry Policy

Webhook deliveries retry with backoff when your endpoint does not return a 2xx response.

Recommended Flow

1. Subscribe to PAYMENT_SETTLED, PAYMENT_FAILED, PAYMENT_EXPIRED, and ORDER_FULFILLED.
2. Add bridge events if you need cross-chain payout status.
3. Verify signature and timestamp.
4. Persist by X-Webhook-Id for idempotency.
5. Update your merchant order record using data.order.id and data.payment.id.