How it works
1
Register an endpoint
POST /v2/webhook-endpoints with your URL and the events you want.
The response carries the endpoint’s signing secret (whsec_…). Store it: it is shown only once.2
Dcycle sends the events
Each event is a
POST with a JSON body, signed with your secret in the Dcycle-Signature header.3
Answer 2xx quickly
Verify the signature, store the event and answer any
2xx within 10 seconds. Do the heavy work afterwards. Any
other answer, a timeout or a network error is retried.x-organization-id it was created with).
Events
Every event has the same envelope:
GET /v2/ingest-jobs/{id}/items?status=failed.
Request headers
Verifying the signature
v1 is the HMAC-SHA256, keyed with your secret, of the timestamp t, a dot, and the raw request body. Compute
it over the bytes you received, before parsing the JSON, and compare in constant time. Reject requests whose t is
more than 5 minutes old to stop replays.
Retries and failures
- At-least-once. An event can arrive more than once. Deduplicate on
id(orDcycle-Event-Id). - Order is not guaranteed. Use the payload’s timestamps and statuses, not the arrival order.
- Retry schedule. An attempt fails on any non-
2xxanswer, a timeout (5 s to connect, 10 s to answer) or a network error. Redirects are not followed. Dcycle retries after 1 min, 5 min, 30 min, 2 h, 6 h and 12 h: seven attempts over about 21 hours, then the delivery isfailed. - Automatic disabling. After 5 deliveries in a row end
failed, the endpoint is disabled (disabled_reason: TOO_MANY_FAILURES) and its creator is notified in the app. Fix your server and re-enable it withPATCH{"enabled": true}. - Delivery log. List Webhook Deliveries shows every delivery with its status code, error and next retry.
URL requirements
The URL must usehttps and resolve to a public address. Private, loopback and link-local addresses (10.x,
192.168.x, 127.0.0.1, 169.254.169.254, …), localhost and URLs with credentials are rejected when you
register the endpoint, and the name is resolved again before every request.
Endpoints
List Webhook Endpoints
Endpoints of your organization
Get Webhook Endpoint
One endpoint by id
Create Webhook Endpoint
Register a URL and get its secret
Update Webhook Endpoint
Change URL, events or re-enable it
Delete Webhook Endpoint
Stop sending to a URL
Rotate Webhook Secret
Replace the signing secret
Send Test Event
Check your server end to end
List Webhook Deliveries
What was sent and how it went