Webhook events
Recover recent events and understand the signed delivery envelope.
On this page
List events
/v1/profiles/{profileId}/webhook-eventsAuthentication: Bearer key · Required scope: invoices.read
Send Authorization: Bearer. No request body. Returns 200 with {items, nextCursor}, newest first, covering the last 30 days.
Items contain the invoice as it is when listed. The endpoint excludes webhook.test events, not test-mode payment events. Store and mode boundaries still apply.
| Field | Details |
|---|---|
profileIdpath · required UUID | The profile that owns your API key. |
limitquery · integer | 1–100; default 50. |
cursorquery · string | The previous response’s nextCursor. Omit for the first page. |
typequery · event name | Optional single event type from the list below. |
Event envelope
| Field | Details |
|---|---|
id, typestrings | Stable event ID and event type. Deduplicate by id. |
livemodeboolean | false for test-mode payments. |
sequenceinteger | Increasing sequence per invoice; arrival order is not guaranteed. |
timestamptimestamp | Event creation time in UTC. |
data.invoiceobject | Owner invoice representation, including metadata and payment/settlement state. |
data.heldobject | null | For invoice.held: amount in base units, reason and nullable optionId. Otherwise null. |
Event types
| Field | Details |
|---|---|
invoice.detectedpayment | A transfer was observed; confirmation is still needed. |
invoice.partially_paidpayment | Confirmed amount is below the amount owed. |
invoice.paidpayment | Payment is complete. Verify canonical state before fulfillment. |
invoice.settledsettlement | Funds settled into the profile wallet. |
invoice.expired, invoice.canceledclosure | Checkout expired or the invoice was canceled. |
invoice.heldheld money | Money is held separately for the payer. |
invoice.openpayment | A chain reorganization removed the observed payment. |
invoice.reopenedpayment | An expired, partly paid invoice was reopened. |
Errors
Responses use {error: {code, message}}. Missing or invalid credentials return 401; missing scope or a different profile returns 403. Objects outside the caller’s store or mode are hidden with 404.
Invalid values return 422 invalid_value. Rate limiting returns 429 rate_limited with Retry-After. A starting network can return 503 network_not_ready; an unexpected server error returns 500 internal.