Receive callbacks
After you register a callback address, we send it signed events when a task finishes and when its charge is settled.
On this page
Callbacks save you from polling: when a task finishes we send a POST request to the HTTPS address you registered.
Register an address
- On the Callbacks page of the console, add an HTTPS address and verify it. Keep the signing secret
signing_secretshown at registration. - When you create a task, put
callback_urlin the body. It must match a verified, unexpired address of your team that has not been removed, byte for byte; otherwise the answer is400 callback_target_not_verified. - When an event arrives, verify its signature before you handle the body.
Two events
| Event | When it is sent |
|---|---|
task.completed | After the task succeeds, fails or is cancelled; a succeeded task finishes delivery first. |
task.billing_settled | After task.completed is delivered or abandoned and the charge is settled. Not sent for a task still unsettled thirty days after completion. |
Both bodies are task snapshots without download links; read the task when you need to download.
Your response and retries
Only a 2xx response confirms receipt. Other answers and timeouts are retried: after the first failure we wait 10 seconds, 1 minute and 5 minutes, then try every hour, for up to 7 days per event. The 7 days of task.billing_settled start when it is first sent.
Deduplicate
Each event is delivered at least once and may arrive twice. After verifying the signature, deduplicate on event_id inside the body; the Chenvoya-Event-Id header is not signed and is only a convenience copy. Keep processed event IDs for at least 7 days and 5 minutes. Retries keep the event ID and the original body bytes.
Remove an address
After you remove an address in the console no new delivery starts, although an attempt already being sent may still arrive. The console shows delivery records; the current status and the download of a task always come from reading the task.