# Receive callbacks

After you register a callback address, we send it signed events when a task finishes and when its charge is settled.

Callbacks save you from polling: when a task finishes we send a `POST` request to the HTTPS address you registered.

## Register an address

1. On the [Callbacks](./callbacks.html) page of the console, add an HTTPS address and verify it. Keep the signing secret `signing_secret` shown at registration.
2. When you create a task, put `callback_url` in the body. It must match a verified, unexpired address of your team that has not been removed, byte for byte; otherwise the answer is `400 callback_target_not_verified`.
3. When an event arrives, [verify its signature](./api-docs-en-callbacks-verify.md) before you handle the body.

## Two events

| Event | When it is sent |
| --- | --- |
| [`task.completed`](./api-docs-en-api-events-task-completed.md) | After the task succeeds, fails or is cancelled; a succeeded task finishes delivery first. |
| [`task.billing_settled`](./api-docs-en-api-events-task-billing-settled.md) | 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.

## Next steps

- [Verify callback signatures](./api-docs-en-callbacks-verify.md): Use the signing secret from registration to check that every event comes from us.
- [Receive a task completion notification](./api-docs-en-api-events-task-completed.md): Chenvoya sends task.completed when a task reaches succeeded, failed or cancelled.
- [Receive a billing settlement notification](./api-docs-en-api-events-task-billing-settled.md): Chenvoya sends task.billing_settled after task.completed is delivered or abandoned and settlement reaches settled or settled_with_receivable.