Webhooks

Signed HTTP callbacks Skipo sends when your transactions change, so you do not have to poll.

Endpoints are registered from the Skipo dashboard, not through this API — the one operation in this section is the public JWKS you verify deliveries against.

The envelope

Every delivery has the same outer shape; the resource snapshot is in data.

Field	Type	What it is
id	string	Logical event id. Your idempotency key — stable across retries and resends.
webhookId	string	The endpoint that received the delivery.
eventType	string	One of the seven below.
resourceId	string | null	Id of the affected resource.
createdAt	number	Event time, epoch milliseconds — not ISO-8601. Timestamps inside data are ISO-8601.
data	object	Snapshot of the affected resource.

Each delivery also carries skipo-webhook-delivery-id, skipo-webhook-event and skipo-webhook-signature headers.

The seven events

Event	When	data shape
withdrawal.created	A withdrawal is created and the balance frozen.	Movement
withdrawal.status.updated	The withdrawal changes status, terminal included.	Movement
deposit.created	A deposit is detected and booked.	Movement
deposit.status.updated	The deposit changes status, terminal included.	Movement
order.created	A convert order is placed at confirm, with status: "NEW".	Order
order.status.updated	The order changes status.	Order
fill.created	A fill executes against an order.	Fill

Subscribe exactly (withdrawal.created), by category (withdrawal.*) or globally (*). The subscribable categories are withdrawal.*, deposit.*, order.* and fill.*.

Ignore event types you do not recognise — new ones can appear at any time, and new fields can appear inside data.

The three data shapes

• Movement (withdrawal.*, deposit.*) — mirrors the WithdrawalResource / DepositResource schemas in this reference, including the top-level transactionHash and bankReference. Status values: PENDING, IN_PROGRESS, COMPLETED, FAILED.
• Order (order.*) — mirrors OrderResource: baseAmount/quoteAmount requested, filledBaseAmount/filledQuoteAmount executed so far, plus onCredit. Status values: NEW, PARTIALLY_FILLED, FILLED, FAILED.
• Fill (fill.created) — mirrors FillResource, with orderId pointing at the parent order. A fill has no status: if it reached you, it executed.

All three always carry assetFormat, multiplier and a base block, so one amount reader works for all of them. Amounts at the top level are always rebased — a webhook carries no query string, so it cannot honour assetFormat. Comparing them against a REST read taken with assetFormat=base will not reconcile: the two are in different units and neither is wrong.

Two things that break integrations

• A fill is not ordered against its order. Deliveries are causally ordered per (endpoint, resourceId), and an order and its fills have different resourceIds — so a fill.created can arrive before its own order.created. Store it and reconcile; do not treat an orphan fill as an error.
• The status channel carries transitions, not a log. You are not guaranteed one event per internal transition, and a resource can be born terminal (.created and .status.updated both COMPLETED, sometimes in the same millisecond). Treat each payload as current state.

Full detail, worked payloads and verification code: https://docs.skipo.com/concepts/webhooks

GET /v2/.well-known/webhook-jwks.json

Webhook signing JWKS

Public JSON Web Key Set for verifying the EdDSA signature on webhook deliveries. Select the key by the kid in the delivery signature header.

Respuestas

Código	Descripción	Cuerpo
200	JWKS document — { "keys": [...] }.	—
500	application/problem+json (RFC 9457) — branch on code, not on the status: internal_error (retryable).	—

---

Esquemas

Problem

Campo	Tipo	Descripción
type	string	Stable problem-type URI. Resolves to docs for this error. Ej.: https://docs.skipo.com/errors/rate_limited.
title	string	Short, human-readable summary (stable, English). Ej.: Rate limit exceeded.
status	number	HTTP status code. Ej.: 429.
code	string	Stable machine-readable error code (equals the last path segment of type). Ej.: rate_limited.
retryable	boolean	Whether retrying the identical request may succeed. Ej.: true.
detail (opcional)	string	Human-readable, possibly localized detail.
instance (opcional)	string	The request path that produced the error.
traceId (opcional)	string	Trace id — joins BigQuery api_request and Cloud Logging.

---

Volver a la referencia de endpoints. Ver también: Paginación · Errores · Ids y correlación.