Skip to main content
A webhook endpoint is an HTTPS URL of yours that Dcycle calls when an event happens in your organization, for example when a bulk ingest job finishes. Your integration reacts at once instead of polling.
Beta. The webhooks API is in beta: the contract may still change before general availability. Ignore unknown fields in the payload so new ones do not break you.

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.
Only organization admins can manage endpoints, with an API key or from the app. An endpoint receives the events of the organization that registered it (the x-organization-id it was created with).

Events

Every event has the same envelope:
The payload is a summary. Fetch the details you need with the API, e.g. the failed records with 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 (or Dcycle-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-2xx answer, 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 is failed.
  • 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 with PATCH {"enabled": true}.
  • Delivery log. List Webhook Deliveries shows every delivery with its status code, error and next retry.

URL requirements

The URL must use https 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