Webhooks
Get a signed message the moment a Run finishes, so you can stop polling and fetch the file
A Webhook is an address of yours that DocTransform calls each time one of your Runs finishes. Think of a doorbell: instead of asking again and again whether the Run is done, you wait, and DocTransform rings when it is. The ring is a short message called an event. It tells you which Run finished and gives you a link to the file.
Set up a Webhook
You need one thing: an address that starts with https:// and can be reached from the internet. A tool such as Zapier gives you one, and so does your own server.
Open the Webhooks card
Go to your Account page and find the card called Webhooks. Click Add Webhook.
Paste your address
Paste it into Address to send events to. A Run finished and A Run failed are already ticked, and so is For all Templates. Change them only if you need to.
Save and send a test
Click Save Webhook, then Send test event. The answer appears in the Delivery log on the same screen, so you know it works before a real Run.
Copy the Signing secret
Only if your own code will check events: click Show, then Copy, under Signing secret. Zapier, Make and n8n users can skip this.
You can add up to 5 Webhooks, the same on every plan. Webhooks are managed only in the Account page, not through the API. Deliveries never count toward your Quota.
GET /runs/{id} still works and is not going away. Writing code? Read Verify webhooks. Using Zapier, Make or n8n? You only need the address those tools give you.What arrives
Each event is a POST with a JSON body of three parts: type, timestamp (when the Run finished) and data. Every key is always there, and is null when it does not apply, so a tool maps the same fields every time. No file content, column, file name or Template name is ever in it: for details, ask GET /runs/{id}.
run.succeeded is sent when the file is ready:
{
"type": "run.succeeded",
"timestamp": "2026-09-27T10:15:00Z",
"data": {
"run_id": "run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58",
"template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
"status": "succeeded",
"download_url": "https://doctransform.xyz/api/v1/runs/run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58/download?expires=1790763300&signature=0000000000000000000000000000000000000000000000000000000000000000",
"expires_at": "2026-09-30T10:15:00Z",
"error": null
}
}run.failed is sent when a Run ends without a file. It has no link, and error.code is one of the error codes:
{
"type": "run.failed",
"timestamp": "2026-09-27T10:15:00Z",
"data": {
"run_id": "run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58",
"template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
"status": "failed",
"download_url": null,
"expires_at": null,
"error": {
"code": "PIPELINE_FAILED",
"message": "The pipeline failed while running the Template."
}
}
}webhook.test is what Send test event sends. Its link does not work, so ignore it with if type == "webhook.test":
{
"type": "webhook.test",
"timestamp": "2026-09-27T10:15:00+00:00",
"data": {
"run_id": "run_test",
"template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
"status": "succeeded",
"download_url": "https://doctransform.xyz/api/v1/runs/run_test/download?expires=1790590500&signature=0000000000000000000000000000000000000000000000000000000000000000",
"expires_at": "2026-09-28T10:15:00+00:00",
"error": null
}
}Check that an event is real
Anyone who finds your address could post to it. Every event carries a signature that only DocTransform and you can make, so your code can tell a real one from a fake. Verify webhooks shows how, with samples to copy.
Retries and turning off
An event counts as delivered only when your address answers with a 2xx status within 10 seconds. Redirects are not followed. Anything else is tried again, so a short outage on your side loses nothing. After each failed attempt DocTransform waits longer:
| After failed attempt | Wait before the next |
|---|---|
| 1 | 1 min |
| 2 | 5 min |
| 3 | 30 min |
| 4 | 2 h |
| 5 | 6 h |
| 6 | 12 h |
| 7 | 24 h |
| 8 | 18 h |
That is 9 attempts over about 2.6 days (62 h 36 min, plus or minus 10 %). A repeat of an event you already handled is normal, so see Stop replays and duplicates.
When deliveries fail
The Webhook stays On and shows that it is failing. Open its Delivery log to see each attempt and why it failed. You get an email after 24 hours of failing. Once your address answers again, the next attempt delivers the event.
The Delivery log gives every failed attempt one of these reasons:
| Reason | In plain words | What to do |
|---|---|---|
WEBHOOK_UNREACHABLE | We could not reach your address: it does not exist, is offline or refused us. | Check the address for typos and that the receiver is running. |
WEBHOOK_TIMEOUT | Your address took longer than 10 seconds to answer. | Answer first and do the slow work afterwards. |
WEBHOOK_REJECTED | Your address answered, but with an error instead of a 2xx status. | Read your receiver's own log to see why it said no. |
WEBHOOK_REDIRECTED | Your address sent us on to another address, and we never follow that. | Paste the final address instead. |
WEBHOOK_URL_BLOCKED | The address points inside a private network, so we stopped sending to it. | Use a public https address. To try things on your own computer, see Testing webhooks locally. |
WEBHOOK_SECRET_UNREADABLE | We could not read the Webhook's Signing secret, so nothing was sent. | Open the Webhook and click Change secret. |
WEBHOOK_DISABLED | The Webhook was Off, so the event was not sent. | Click Turn on. |
When a Webhook turns off
After 10 failed attempts in a row, spread over more than 5 days, the Webhook turns Off and you get a second email. Nothing more is sent. Fix your address, then click Turn on: it offers to resend the deliveries that were stopped when it turned Off, from the last 3 days. A Run that finished while the Webhook was Off is not sent. Get its file with GET /runs/{id}/output, or from its download link while that lasts. You can also click Resend on any single delivery.
When your address says gone
If your address answers 410 Gone, the Webhook turns off at once, because that answer means it will never come back. This often happens when a Zap or scenario is deleted or left off. Bring the receiver back, then click Turn on.
Download the file
download_url downloads the file with no API Key until expires_at. That is 3 days after the Run finished when a Webhook receives the Run, and 30 minutes otherwise, which is also how long GET /runs/{id}/output works. It is null on run.failed, and on a delivery sent after the file expired, such as a late Resend. An expired link answers DOWNLOAD_LINK_EXPIRED: run the Template again.
Testing webhooks locally
DocTransform sends only to public https addresses, so localhost is refused. A tunnel gives your local server a public address. This one needs no account:
cloudflared tunnel --url http://localhost:8000Paste the address it prints, plus your path, into a Webhook, then click Send test event. ngrok does the same job. Delete the Webhook when you are done, because the tunnel address changes every time.
See what happened
API activity on your Account page lists every request your API Keys made in the last 90 days, refusals included. Each Webhook's Delivery log shows every attempt with its answer and a Resend button. Both are linked by the Run id: click See this Run to jump between them.