Skip to main content
A webhook is a signed POST that Doconda sends to your HTTPS endpoint every time a document in the project finishes. It lets you take each document to your system before its retention ends, without polling the API. This is useful for:
  • Storing every finished file in your own bucket or database.
  • Telling your user their document is ready, or why it failed.
  • Running many documents in background mode without keeping connections open.

How it works

  1. You register an endpoint URL in a project. Doconda returns its secret.
  2. When a document finishes, Doconda sends a POST with a small JSON body and three signature headers.
  3. Your server checks the signature, answers 2xx, and fetches the document with the API.
  4. If your server doesn’t answer 2xx within 20 s, Doconda retries.

Register an endpoint

In the dashboard, go to Webhooks → Add endpoint, or use the API:
The response carries the secret (whsec_…) only once: store it, for example as DOCONDA_WEBHOOK_SECRET.
  • The URL must be HTTPS on a public address; anything else is rejected with 422 webhook_url_invalid.
  • A project can have up to 20 endpoints; one more is rejected with 422 too_many_webhook_endpoints.
  • Each endpoint belongs to one project and receives that project’s documents only.
  • webhooks.list() (GET /webhook-endpoints) lists them, and webhooks.delete(id) (DELETE /webhook-endpoints/{id}) deletes one.

What Doconda sends

By default, every final event: document.ready, document.failed, document.canceled, and after a hand-edited file is saved, document.updated or document.update_failed. To receive only some, pass event_types when you create the endpoint.
The body never carries the document’s content. Fetch it with GET /documents/{id} and download its files. Converting a file sends no webhook: its response already carries the result.

Check the signature

Doconda follows Standard Webhooks. Each request has three headers: The SDKs check it for you:
Pass the body exactly as it arrives: re-serializing the JSON changes the bytes and the signature no longer matches. The check raises an error (ValueError in Python, Error in TypeScript) when a header is missing, the signature doesn’t match, or the timestamp is more than 5 minutes from now.

Retries

Answer with a 2xx within 20 seconds. Any other status, a timeout or a connection error counts as a failure, and Doconda retries after 5 s, 30 s, 2 min, 10 min, 30 min, 1 h, 3 h and 6 h. That is 9 attempts over about 11 hours; after the last one, the event is dropped. Behavior to be aware of:
  • The same event can reach you more than once. Deduplicate by webhook-id.
  • Events can arrive out of order. Use timestamp, or fetch the document, to know its current state.
  • Deleting an endpoint stops its pending retries.
Answer 2xx as soon as the signature checks out, and download the files afterwards, so slow downloads don’t cause retries.

Next steps

Events

Every event type and what its data carries.

How long it is kept

Know how long you have to take each document.