API reference
Rather than polling, subscribe a URL and hear about signatures, views and access requests as they happen. Every delivery is signed with HMAC-SHA256, retried on failure and kept in a log you can read back. This is the shape Zapier, Make and n8n expect.
Base URL https://xdocs.io/api/v1, with Authorization: Bearer xdk_… on every request. Pagination, rate limits, scopes and error codes are the same for every endpoint and are described once, in how the API behaves.
Subscriptions an integration creates and removes on its own, one per thing it wants to hear about. This is the shape Zapier, Make and n8n expect, and a subscription is the same endpoint row the developer settings page shows with its delivery log — so these calls see and change the workspace's endpoints wherever they were made.
/api/v1/hooksdocuments:readEvery webhook endpoint in the workspace, newest first — including those added on the settings page — and the catalogue of events.
Returns
{ data: Hook[], events: [{ name, description }] } — events includes ping, the test event
/api/v1/hooksdocuments:writeSubscribe a URL. Re-subscribing the same URL to the same events returns the existing row rather than a duplicate, because platforms retry.
Body (JSON)
urlstringrequiredeventsstring[]event either, means every event.eventstringevents.Returns
201 { data: Hook & { secret } } — the signing secret. An identical re-subscribe answers 200 with the existing row and its secret, and switches it back on if it had been switched off.
422 Unknown event names; `details.known` lists the valid ones./api/v1/hooks/:iddocuments:readOne subscription, with its recent health.
Returns
{ data: Hook } — id, url, events, active, failureCount, lastStatus, lastAttemptAt, createdAt. failureCount is consecutive failed deliveries; at 10 the endpoint is switched off.
/api/v1/hooks/:iddocuments:writeChange the URL or events, or switch it on and off. Switching it on resets the failure count.
Body (JSON)
urlstringeventsstring[]activebooleanReturns
{ data: Hook }
422 Unknown event names; `details.known` lists the valid ones./api/v1/hooks/:iddocuments:writeUnsubscribe. Idempotent: a second call is a 204 too.
Returns
204
/api/v1/hooks/:id/pingdocuments:writeSend a ping delivery now, whatever the endpoint subscribes to and even if it is switched off, and report how it answered.
Returns
{ data: Delivery & { payload } } — status, responseStatus, attempts, error
422 The test delivery could not be recorded./api/v1/hooks/:id/rotatedocuments:writeReplace the signing secret. The new one is returned once.
Returns
{ data: Hook & { secret } }
/api/v1/hooks/:id/deliveriesdocuments:readEvery delivery attempt, newest first — which is how a webhook that “does not work” turns out to be one specific 401.
Query parameters
eventstringstatusstringpending, delivered or failed. Anything else is a 400.includestringpayload adds the body that was sent.limitintegercursorstringnextCursor. Opaque — pass it back unchanged.Returns
{ data: Delivery[], nextCursor } — id, endpointId, event, status, attempts, responseStatus, error, deliveredAt, createdAt, payload?
/api/v1/hooks/samplesdocuments:readRecent real payloads for one event, for a platform's “load sample” step. A synthetic one of the same shape when nothing has happened yet.
Query parameters
eventstringReturns
{ data: object[] } — up to three delivered bodies, each { id, event, createdAt, data }
422 Unknown event name; `details.known` lists the valid ones.What a subscription can listen for. Signing and verifying deliveries is covered on the overview.