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
- You register an endpoint URL in a project. Doconda returns its
secret. - When a document finishes, Doconda sends a
POSTwith a small JSON body and three signature headers. - Your server checks the signature, answers
2xx, and fetches the document with the API. - If your server doesn’t answer
2xxwithin 20 s, Doconda retries.
Register an endpoint
In the dashboard, go to Webhooks → Add endpoint, or use the API: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, andwebhooks.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.
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:
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 a2xx 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.
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.