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).
Webhooks are for integrations: ingest_job.finished is sent for the jobs your organization submits with an API
key (their source is api_bulk). A job a person starts while signed in to Dcycle, such as a waste created from the
app’s form, notifies that person in the app instead and sends no webhook (its source is app); nor does an
employee’s answer to the commuting survey (survey). Likewise, file.finished is sent for the files uploaded with an
API key; a file a person uploads in the app, or through the Dcycle MCP, which acts for that person, sends none.
Only asynchronous requests (202 Accepted) send ingest_job.finished. A
synchronous create (201 Created:
facilities, vehicles, and own workforce employees, trainings and absences) answers with the created records, so the
answer is the result and no webhook is sent.
Groups of organizations
A job’singest_job.finished reaches the endpoints of the organization in the request’s x-organization-id. If your
group sends each subsidiary’s data with that subsidiary’s x-organization-id (purchases, business travels and logistics
requests always belong to the request’s organization, so a group sends them this way), register an endpoint in each organization you
send as. List Ingest Jobs from the parent organization lists the subsidiaries’ jobs
too, and each of those jobs notifies the endpoints of its own subsidiary.
Events
Every event has the same envelope:
id is the event (the same on every retry: deduplicate on it), and data.id
is the job the event is about (the id you got in the 202 of POST /v2/wastes). data.entity_type and
data.operation say what the job did, e.g. wastes + create.
api_version dates the envelope and payload format. A breaking change to a payload ships under a new version;
new fields can appear without one, so ignore the ones you do not use.
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.
File events
file.finished is sent each time an uploaded spreadsheet stops with nothing left for Dcycle to do on it, with the file’s
status, step, reason, auto_import and review_url as Get a File (v2) answers
them at that moment:
One file can send more than one:
needs_review when the automatic import stops, then completed once a person
finishes the import. Each stop sends one event. A file whose upload already answers needs_review (a suspected
duplicate) sends nothing until it moves again, and nor does a spreadsheet the classifier finds no category for, which
ends failed with step not_processed. Documents read by OCR (PDF, images) send no file.finished yet: read
them with GET /v2/files/{file_id}.
data carries all of them.
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. The key is
the whole secret, whsec_ prefix included, as UTF-8 bytes. Compute the HMAC 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 to each address of your host, 10 s to answer, 20 s for the whole attempt) 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 what
was sent (
payload), what your server answered (last_status_codeand the start of its body inlast_response_body), why the last attempt failed (last_error_code) and the next retry. Retry Webhook Delivery sends one again on demand, with the same eventid.
Debugging a failed delivery
last_error_code says why the last attempt failed, and last_error gives the detail:
last_response_body keeps up to the first 2 KB of your server’s body. Once the status code has arrived, Dcycle waits at
most 10 more seconds for that body (and never past 20 seconds from the attempt’s start), and the body never changes the outcome. If it looks garbled, your server compressed
it even though Dcycle sends Accept-Encoding: identity.
Once fixed, send a test event or
retry the delivery.
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
On the free plan an organization can list, open and delete its endpoints and read their deliveries; creating, changing, testing them, retrying their deliveries and rotating their secret need a paid plan (403 PLAN_FEATURE_NOT_INCLUDED).
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
Retry Webhook Delivery
Send a past event again