Module callback 

Available on crate feature serve only.

Per-run completion callbacks (#481).

A caller that submits a run over HTTP usually owns a job record and wants to be told when the run finishes, at an endpoint that varies per job. The config-declared notifications: block cannot express that — it is static per pipeline — so the callback destination rides the submission instead (POST /v1/runs, POST /v1/templates/{id}/runs) and is stored on the run record.

Delivery guarantee: at-most-once

The callback fires from the in-process terminal transitions — fire is called by runner::finalize, by runner::maybe_finalize_parent (the sharded parent), and by the pending-cancel handler. It is not fired by the recovery sweeps that live inside the history backend (lease-expiry orphan recovery, reclaim-poison, the sharded-parent completion sweep), because those run inside the SQL layer and never see this dispatcher.

So: if the instance owning a run dies and the run is later failed by lease recovery, no callback is delivered. A caller must therefore treat a missing callback as “unknown”, not as “still running”, and reconcile against GET /v1/runs/{id}, which is always authoritative. This is stated in the HTTP API reference too — it is the one thing that will hang an integration that assumes otherwise.

Egress

CallbackSpec::validate restricts the scheme to http/https and refuses link-local / cloud-metadata targets, which is the concrete SSRF risk called out in the serve cookbook. --callback-allow-host narrows it further to an explicit allowlist. Note the broader posture is unchanged: a caller who can submit a run can already point a rest source anywhere, so this guard closes the metadata hole rather than pretending to be a general egress control.

Structs

CallbackSpec

A caller-supplied completion callback, carried on the run record.

Constants

RESERVED_BODY_KEYS

Top-level keys the callback body always carries. extra_fields may not shadow any of them — the same fail-fast rule the notify webhook uses, for the same reason: a typo’d status key would otherwise let a submission spoof the very signal the receiver keys off.

Functions

fire

Deliver the completion callback for rec, if it has one that subscribes to its terminal status. Never propagates an error: a callback is best-effort and must not affect the recorded outcome of a run that already finished.