1.  [Documentation](/en/docs)
2.  [API](/en/docs/api/quickstart)
3.  Webhooks

# 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](/account#webhooks) 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](/en/docs/api/verify-webhooks). Using [Zapier, Make or n8n](/en/docs/api/zapier-make-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
      }
    }

Copy

`run.failed` is sent when a Run ends without a file. It has no link, and `error.code` is one of the [error codes](/en/docs/api/errors-and-limits):

    {
      "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."
        }
      }
    }

Copy

`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
      }
    }

Copy

### 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](/en/docs/api/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](/en/docs/api/verify-webhooks#replays).

### 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](#test-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](/en/docs/api/errors-and-limits#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

Copy

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.
