Pausing a Subscription
Pause a subscription when its deliveries should stop for a while: the receiving system is under maintenance, its template is being fixed after a schema change, or you are investigating something. Nothing is lost.
What a pause does
Section titled “What a pause does”- Events keep fanning out to the subscription. Each delivery is recorded with status paused, and nothing is queued or attempted.
- Deliveries that were already queued or retrying when you paused are held too: their next attempt becomes paused instead of being sent.
- Other subscriptions on the same webhook are unaffected. Pausing the whole
webhook, by hand or when Sparrow
auto-disables it,
works the same way for all of its subscriptions: deliveries are held as
paused, and resuming the webhook reports how many
(
paused_deliveries) so you can retry them withstatus=paused&webhook_id={webhook_id}. - A pause is not a failure of the receiving system, so it never affects the webhook’s health or raises health alerts.
curl -X POST http://localhost:8080/v1/consumers/acme/subscriptions/{subscription_id}:pause \ -H 'Content-Type: application/json' \ -d '{"reason": "receiver maintenance until Friday"}'The subscription then shows paused: true, paused_at and paused_reason.
Pausing again updates the reason and keeps the original time. In the UI, use
Pause on the subscription; its card shows the reason while it is paused.
Seeing what was held
Section titled “Seeing what was held”Held deliveries are ordinary deliveries with status paused:
- The delivery lists (all deliveries, or one webhook’s) show them with a
Paused badge, and the status filter has a Paused option
(
GET /v1/consumers/{consumer}/deliveries?status=paused). - Each one records why it was held in
error_message, shown on the delivery page:Held: subscription is paused (<your reason>),Held: webhook is paused, orHeld: webhook was auto-disabled. - A delivery that was already retrying when the pause began keeps the error of its last failed attempt alongside the hold.
- The event itself appears in the event history as usual, with its paused deliveries listed under it.
Resuming
Section titled “Resuming”curl -X POST http://localhost:8080/v1/consumers/acme/subscriptions/{subscription_id}:resumeNew deliveries are attempted again straight away. Deliveries held during the pause are not sent automatically: you decide what to replay. The response tells you how many there are and when the pause began:
{ "subscription_id": "…", "paused": false, "paused_since": "2026-09-30T10:00:00Z", "paused_deliveries": 42 }To send them, snapshot them with the delivery list and start a batch retry
with the retry_id the list returns:
curl "http://localhost:8080/v1/consumers/acme/deliveries?status=paused&subscription_id={subscription_id}&created_after=2026-09-30T10:00:00Z&prepare_retry=true"# -> {"items": [...], "retry_id": "3f2a9c1e-…", ...}
curl -X POST http://localhost:8080/v1/consumers/acme/deliveries:retryBatch \ -H 'Content-Type: application/json' -d '{"retry_id": "3f2a9c1e-…"}'The retry runs in the background. The response is the job, whose id is that
same snapshot ID; follow its status, processed and failed counts with
GET /v1/consumers/acme/retry-jobs/3f2a9c1e-….
Narrow created_after (or add created_before) to replay only part of the
window. In the UI, resuming a subscription that held deliveries offers
Retry paused deliveries.
Pausing from an import
Section titled “Pausing from an import”When importing event types, --pause-affected (API:
subscription_policy: "pause") pauses every subscription whose template fails
against the new schema, in the same transaction, with the import as the
reason. See Moving Event Types Between Environments.
Where pause fits in a delivery
Section titled “Where pause fits in a delivery”flowchart TD
accTitle: Delivery outcomes
accDescr: Delivery outcomes: an accepted event fans out; inactive webhooks get nothing; paused subscriptions get a paused delivery with no job until resumed and retried; otherwise a job runs, the transform renders or fails (fail marks template_error, fallback sends the envelope), the request is sent, and only receiver responses count toward webhook health.
E["event accepted,<br>event_version recorded"] --> FO["fan-out to matching subscriptions"]
FO --> PS{"webhook or subscription paused?<br>(incl. auto-disabled)"}
PS -- yes --> PR["delivery row, status paused,<br>no job queued"]
PR -. "resume, then retry" .-> JOB
PS -- no --> JOB["delivery row pending,<br>job queued"]
JOB --> HP{"paused since queued?"}
HP -- yes --> PR
HP -- no --> T{"transform enabled?"}
T -- no --> ENV["default envelope"]
T -- yes --> RN["render template<br>(template_missing_key)"]
RN --> OK{"rendered?"}
OK -- yes --> SEND["HTTP request"]
OK -- no --> OE{"on_transform_error"}
OE -- fail --> TE["failed, template_error:<br>not retried automatically"]
TE -. "fix template, retry" .-> JOB
OE -- fallback --> ENV2["default envelope,<br>template_error recorded"]
ENV --> SEND
ENV2 --> SEND
SEND --> RES{"response"}
RES -- "expected 2xx" --> S["success"]
RES -- retryable --> RT["retry with backoff"]
RES -- permanent --> FL["failed"]
S --> H[("webhook health")]
RT --> H
FL --> H
H -. "failing for SPARROW_AUTO_DISABLE_AFTER" .-> AD["webhook auto-disabled<br>(sparrow.webhook.disabled)"]
Only the receiving system’s responses count toward the webhook’s health. Paused deliveries and template errors never do.