
# Webhook targets

A webhook job sends an HTTP `POST` with a JSON body to the job's URL each time a
run is due, when you choose **Run now**, or when you send a test event. By
default the request carries this body:

```json
{
  "run_id": "…",
  "job_id": "…",
  "scheduled_for": "2030-01-02T03:04:05Z",
  "trigger": "scheduled"
}
```

`trigger` is `scheduled`, `manual` or `test`. `scheduled_for` is the time the run
was due; for a manual run or a test event, it is the time the run was created.

Every request has `Content-Type: application/json` and `User-Agent:
tron-scheduler`. Tron does not follow redirects, and a single request is capped
at 30 seconds.

## Target requirements

The URL must use `http` or `https`, and the endpoint must be reachable from the
public internet. Tron refuses loopback, private, link-local and shared-address
(carrier-grade NAT) addresses, including hostnames that resolve to them, and it
does not use proxies. For such a target no request is sent and the run fails
with a **target blocked** failure category. Tron never retries a blocked or
invalid target.

## Choose the request body and headers

Under **Webhook request** in the job form, you can keep the saved request, remove
it, or replace it. Replacing it lets you define a body template and custom
headers. Saving a replacement overwrites the whole saved request: every header
is replaced by the ones you list.

### Body template

A body template is JSON that Tron sends instead of the default body. It must be
valid JSON of at most 64 KiB. Write `{{name}}` inside a JSON string, or inside an
object key, to insert a value when Tron sends the request:

| Variable | Value |
| --- | --- |
| `{{run_id}}` | The run's identifier. |
| `{{job_id}}` | The job's identifier. |
| `{{scheduled_for}}` | The time the run was due, as UTC (`2030-01-02T03:04:05Z`). |
| `{{trigger}}` | `scheduled`, `manual` or `test`. |
| `{{attempt}}` | The attempt number, starting at 1, inserted as text. |

For example:

```json
{
  "event": "tron.run",
  "id": "{{run_id}}",
  "kind": "{{trigger}}",
  "attempt": "{{attempt}}"
}
```

Variable names are lowercase, and there are no spaces inside the braces. An
unknown variable, an unmatched `{{` or a stray `}}` is rejected when you save.
Inserted values are escaped for JSON, and Tron sends the result as compact JSON.
Verify a signature against the bytes you receive, never against a body you
parsed and re-serialised.

### Custom headers

Add up to 32 headers. A name is at most 128 bytes and a value at most 8 KiB.
Tron sets these headers itself, so you cannot override them: `Host`,
`User-Agent`, `Content-Type`, `Content-Length`, `Transfer-Encoding`,
`Tron-Signature`, `Tron-Timestamp` and `Tron-Delivery-Id`.

Each header is either:

- **Public (shown when you edit)**, so you can read it back later; or
- **Secret (never shown again)**. Tron stores the value encrypted and never
  displays it again. To keep a secret header when you later replace the
  request, enter its value again.

Use a secret header for anything that works like a credential, such as a bearer
token. The request preview and the job page show secret headers as stored with
their value hidden, and Tron replaces any request value that a receiver echoes
back in a recorded response excerpt (see Delivery attempts below) with
`[redacted]`.

## Verify that a request came from Tron

Every request carries two headers, whether or not the job is signed:

| Header | Meaning |
| --- | --- |
| `Tron-Delivery-Id` | The run's identifier. It is the same on every attempt of that run. |
| `Tron-Timestamp` | When Tron signed this attempt, as Unix seconds. |

When the job has a signing secret, the request also carries `Tron-Signature`. A
job without a signing secret sends no `Tron-Signature` header.

### Create and rotate the signing secret

Open a webhook job and find **Webhook signing**. Choose **Create signing secret**.
Tron shows the secret once. Copy it into your receiver's configuration at that
moment: it cannot be shown again, and if you lose it you rotate to a new one.
The secret is a 43-character string. Use it exactly as shown, as text. Do not
decode it.

Choose **Rotate signing secret** to replace it. The new secret is shown once,
and the previous secret keeps working for 24 hours so you can deploy the new one
without losing deliveries. While two secrets are valid, `Tron-Signature` holds
one signature per valid secret, separated by commas; the secrets list shows when
each is valid from and until.

### Check a signature

Tron computes a signature over the timestamp, a literal `.` character, and the
exact request body bytes, using HMAC-SHA256 with the signing secret as the key.
Each `Tron-Signature` member is `v1=` followed by the lowercase hexadecimal
digest. In language-neutral steps:

```text
timestamp = header "Tron-Timestamp"            (ASCII digits)
body      = raw request body bytes             (before any JSON parsing)
expected  = "v1=" + lowercase_hex( HMAC_SHA256(key = secret, data = timestamp + "." + body) )

reject unless |now_in_unix_seconds - timestamp| <= tolerance
accept if any member of header "Tron-Signature".split(",")
          equals expected, compared in constant time
```

The **Verify a delivery** panel under **Webhook signing** shows a worked example
with a known test key, body and expected signature, so you can check your
verifier before you receive real traffic.

Tron signs each attempt again with a fresh timestamp. A retry therefore carries
a new `Tron-Timestamp` and `Tron-Signature`, and a short replay tolerance, for
example five minutes, does not reject a late retry. Keep the tolerance short
enough that a captured request cannot be replayed later, and keep your server's
clock accurate.

## Make the receiver safe to call twice

Delivery is at least once. A receiver can act and then fail to answer, and Tron
cannot tell that from a request that never arrived. Use `Tron-Delivery-Id` as the
idempotency key:

1. Before you do the work, record the id in the same transaction as the work,
   or reserve it atomically.
2. If the id is already recorded, answer `2xx` and do nothing more.

The id is the same on every attempt of one run, and different for each run,
including each manual run and each test event. The `run_id` in the default body
is the same value.

## Retries

By default a webhook job makes one attempt: no retries. In the **Retries**
section of the job form you choose how Tron retries:

| Setting | Meaning |
| --- | --- |
| Maximum attempts | Total attempts, including the first, from 1 to 10. 1 means no retries. |
| Wait between attempts (seconds) | The base wait before the next attempt. |
| Wait pattern | **Fixed** waits the same time every time. **Exponential** doubles the wait after each attempt. |
| Longest wait (seconds) | No computed wait exceeds this, up to 3600. |

Retries happen only for the failures you switch on:

| Setting | What it retries |
| --- | --- |
| Retry when the request cannot reach the webhook | Connection and network errors. |
| Retry when the webhook does not answer in time | A request that timed out. |
| Retry on a retryable status | Responses with status `408`, `429` or any `5xx`. |
| Re-send an attempt whose outcome is unknown | An attempt that was in flight when Tron stopped. The receiver may already have it, so turn this on only if it deduplicates on `Tron-Delivery-Id`. |

A `2xx` response always succeeds. Other `4xx` responses and any `3xx` response
are final failures and are never retried, and neither are blocked or invalid
targets.

If a retryable response carries a `Retry-After` header, as a number of seconds
or as an HTTP date, Tron waits for the longer of that time and the configured
wait. `Retry-After` is not limited by **Longest wait**.

A retry starts only if it would begin no later than the job's **Mark late if not
finished within** time after the run was due. If the next attempt would fall
after that, including because of `Retry-After`, Tron makes no further attempt
and the run ends with the last attempt's result. Between attempts the run shows
as **Pending** with its retry time, and you can cancel it. After the last
attempt the run is **Failed**, or **Timed out** if the last request timed out;
there is no separate "retries exhausted" state.

## Delivery attempts

Open a webhook run to see **Delivery attempts**. Each attempt shows its number
and status (**Sending**, **Succeeded** or **Failed**), start and finish times,
duration, HTTP status code, failure category, and, while a retry is waiting, **Retry
due**. The log shows the delivery id the receiver saw. Runs recorded before
attempt logging existed show one summarised attempt marked as such.

Tron does not store network error text, and by default it does not store response
bodies. Turn on **Keep an excerpt of each response body** to store a bounded
**Response excerpt** on each attempt; choose a size limit of 1 to 2048 bytes
(512 by default). The excerpt is plain text with control characters removed, and
Tron replaces anything the request carried, such as header values, signing
secrets and signatures, with `[redacted]`. Turning the setting off again hides
excerpts already stored. The target URL stays part of the job and is not copied
into run history.

Finished runs are pruned oldest first once a job has many, and their attempts go
with them.

## Send a test event

On a webhook job's page, choose **Send test event** to try the whole path before
a real run is due. It creates a run with `trigger` set to `test` and
`scheduled_for` set to the current time, and sends it to the job's real URL with
the job's real body template, custom headers and signature. It follows the job's
retry settings and the same target rules, so a receiver cannot tell it apart
except by `trigger: "test"`. The page shows the result when it finishes, and the
run appears in the job's history labelled **Test event**. A test does not count
as a scheduled run and is not shown on a public job page.

Test events exist only for webhook jobs.

## Delivery outcome

A webhook run succeeds when an attempt gets a `2xx` response. Tron records the
run state, failure category (for example, target blocked), the HTTP status when
there is one, and the duration of each attempt.

See [runs and their states](https://cruma.io/book/tron/runs-and-states.md) for the result shown in Tron.

---

- Book: [Tron (Private preview)](https://cruma.io/book/tron.md)
- Previous: [Jobs and schedules](https://cruma.io/book/tron/jobs-and-schedules.md)
- Next: [Runners](https://cruma.io/book/tron/runners.md)
- Pages: [Home](https://cruma.io/home.md) · [Docs](https://cruma.io/docs.md) · [Pricing](https://cruma.io/pricing.md) · [Share localhost](https://cruma.io/share-localhost.md) · [Webhook testing](https://cruma.io/webhook-testing.md) · [Homelab](https://cruma.io/homelab.md) · [AI coding agents](https://cruma.io/ai-coding-agents.md) · [Cruma vs ngrok](https://cruma.io/ngrok-alternative.md) · [Cruma vs Cloudflare Tunnel](https://cruma.io/cloudflare-tunnel-alternative.md) · [Blog](https://cruma.io/blog.md)
