Guide

Pause And Resume Connections

Pause is a route-level operating control. It lets a source keep accepting provider traffic while one destination branch holds newly routed events until the receiver is ready.

Use this guide to decide when to pause, when to disable, and how to resume without creating a second incident.

Branch State Model

Connection state is branch-local. Pausing a connection does not disable the source, does not stop sibling connections, and does not rewrite destination configuration.

FastHook stores pause state on the connection as paused_at. Active delivery has paused_at set to null. Disabling a connection sets disabled_at and, in the dashboard flow, clears paused_at so the branch does not build held work.

  • Active: paused_at is null and disabled_at is null, so routed events can deliver.
  • Paused: paused_at is an ISO timestamp and new routed events become HOLD for this connection.
  • Disabled: disabled_at is an ISO timestamp and future requests skip this connection.
  • Sibling connections from the same source can keep running.
  • Event retry for a paused connection should wait until the route is resumed.
Pause holds one route; disable stops future routing for that route.

Pause In Dashboard Or API

In the Structured Connections dashboard, open the connection, use the actions menu, and choose Pause connection. The same menu also has Disable connection and Delete connection, so keep the operational intent clear before clicking.

The dashboard currently updates pause state with PATCH /v1/connections/:id and a paused_at value. The public action endpoints PUT /v1/connections/:id/pause and PUT /v1/connections/:id/unpause are also supported.

  • The pause response returns the connection with paused_at set.
  • Use PATCH when an automation runbook owns the exact timestamp it wants to set.
  • Use the action endpoint or CLI when the operator just wants to pause now.
  • Do not include rules in a pause-only PATCH unless you intend to change rules too.
Pause is a connection action. It is different from disabling the connection.
Pause controls
# CLI action endpoint
fasthook connections pause web_xxx

# Equivalent API action endpoint
curl -X PUT "https://api.fasthook.io/v1/connections/web_xxx/pause" \
  -H "Authorization: Bearer fhp_xxx" \
  -H "x-team-id: tm_xxx"

# Dashboard-style focused patch
curl -X PATCH "https://api.fasthook.io/v1/connections/web_xxx" \
  -H "Authorization: Bearer fhp_xxx" \
  -H "x-team-id: tm_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "paused_at": "2026-05-29T22:45:00.000Z" }'

What Happens While Paused

A paused connection still participates in routing. When the source accepts a provider request, FastHook can create event evidence for the paused branch, but the event waits with HOLD instead of immediately creating destination delivery attempts.

This is why pause is useful during receiver maintenance: the provider can continue sending to the source URL and healthy sibling branches can continue delivering, while one receiver branch accumulates held work for later drain.

  • Requests are still accepted or rejected by source settings.
  • Active sibling connections can still deliver.
  • Paused connection events use status HOLD.
  • HOLD events are released by unpause, not by event bulk retry.
  • A disabled connection is skipped for future routing and does not build a backlog.
Paused branches keep evidence as HOLD. Disabled branches are skipped for future requests.
Held branch inspection
fasthook events list --connection_id web_xxx --status HOLD --limit 50

fasthook metrics events \
  --connection_id web_xxx \
  --from 2026-05-29T00:00:00Z \
  --to 2026-05-29T23:59:59Z \
  --measures[] hold_count \
  --measures[] queued_count \
  --measures[] failed_count

Resume And Drain Safely

Unpause only after the receiver is healthy and the destination capacity is set low enough to drain the held work safely. If the backlog is large, lower the destination rate limit before unpausing.

Unpause sets paused_at back to null. Held work then drains through normal delivery controls: destination rate limits, retry strategy, queue timing, and receiver responses still apply.

  • Confirm the receiver is healthy before unpausing.
  • Set or lower destination rate_limit before draining a large HOLD backlog.
  • Watch hold_count, queued_count, failed_count, delivered_count, and attempt responses.
  • Attempts created while draining held work can be traced with trigger UNPAUSE.
  • Retry failed events after the route is unpaused and stable.
  • Document the paused window for later incident review or targeted retry.
Resume by draining. Watch the receiver while HOLD turns into delivery attempts.
Resume controls
fasthook connections unpause web_xxx

curl -X PUT "https://api.fasthook.io/v1/connections/web_xxx/unpause" \
  -H "Authorization: Bearer fhp_xxx" \
  -H "x-team-id: tm_xxx"

curl "https://api.fasthook.io/v1/events?connection_id=web_xxx&status=HOLD&limit=20" \
  -H "Authorization: Bearer fhp_xxx" \
  -H "x-team-id: tm_xxx"

Pause, Disable, Or Stop The Source

Choose the narrowest control that matches the failure. Pause is for a temporary receiver problem where you want to drain later. Disable is for stopping future branches without building a backlog. Source disable is broader and rejects or stops ingress for the source itself.

  • Pause one connection when one receiver is temporarily unhealthy.
  • Disable one connection when that branch should not receive future routed events.
  • Disable a destination when the outbound receiver object should not be used by any connection.
  • Disable a source only when provider ingress for that source should stop.
  • Do not pause every branch if only one destination is failing.

Incident Runbook

During an incident, pause should come after evidence. Confirm the affected branch first, then pause only that connection, then inspect the held and failed window before any retry or replay.

  • Find the failing branch by destination_id or connection_id.
  • Pause the connection that feeds the unhealthy receiver.
  • Keep source auth and sibling connections running when they are healthy.
  • Watch HOLD grow while the receiver is offline.
  • Fix the receiver or destination config.
  • Unpause with a rate limit and watch the drain.
  • Retry failed events only after the resumed route is stable.

Common Mistakes

  • Disabling a connection when you meant to hold and drain it later.
  • Unpausing without a destination rate limit after a large backlog.
  • Pausing the wrong branch because connections were not named clearly.
  • Assuming pause stops provider ingress; sources can still accept requests.
  • Running a bulk retry while the target connection is still paused.
  • Using request replay when only held or failed events on one destination branch need attention.
  • Forgetting that disabling a connection clears paused_at in the dashboard flow.

Next