DocTransform

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.

  1. Open the Webhooks card

    Go to your Account page and find the card called Webhooks. Click Add Webhook.

  2. 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.

  3. 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.

  4. 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.

Note Polling 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 attemptWait before the next
11 min
25 min
330 min
42 h
56 h
612 h
724 h
818 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:

ReasonIn plain wordsWhat to do
WEBHOOK_UNREACHABLEWe 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_TIMEOUTYour address took longer than 10 seconds to answer.Answer first and do the slow work afterwards.
WEBHOOK_REJECTEDYour address answered, but with an error instead of a 2xx status.Read your receiver's own log to see why it said no.
WEBHOOK_REDIRECTEDYour address sent us on to another address, and we never follow that.Paste the final address instead.
WEBHOOK_URL_BLOCKEDThe 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_UNREADABLEWe could not read the Webhook's Signing secret, so nothing was sent.Open the Webhook and click Change secret.
WEBHOOK_DISABLEDThe 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.

Warning Anyone with the link can download the file until it expires. Do not paste it anywhere shared.

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:8000

Paste 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.