Webhooks

A webhook is an address plus a token. Another system posts to it and a run starts.

Access

Each job has its own address and its own token, and the token can be rotated without touching the job. A header secret can be required on top, so a leaked address alone is not enough.

Fields

The plan says which fields the job needs. Two modes exist. Tolerant accepts what arrives and warns about what is missing. Strict rejects a request that does not match the agreed shape, with a message that names the field. Strict is the right choice when the caller is a system you control.

What the caller gets back

An acknowledgement, immediately, when the calling system only needs to know the event was taken.

The result, when the calling system waits for it. That includes files: a generated document comes back in the same response.

A job can also set its own status code from the script, so a caller learns that its input was wrong rather than receiving a cheerful reply with nothing in it.

Order and bursts

Parallel runs requests as they arrive. Sequential puts them in a durable queue and runs them one after another. The queue survives a restart of the platform and nothing is dropped: a burst waits rather than failing. Which mode a job uses is part of its plan, and changing it is done while the job is quiet.

Limits

Sixty requests per minute per token, and a payload of up to 256 kilobytes. Above that the caller is told, not ignored. See Limits and queues.