Instant Trigger health and recovery

Some provider Triggers receive events through managed notification channels or per-account webhook subscriptions. FastHook reconciles those resources, renews expiring channels where required, retries failures, and can use polling fallback for supported Instant Trigger definitions.

Channel states

| State | Meaning | Operator action | | --- | --- | --- | | connecting | Fewer active targets exist than the Trigger expects. | Wait for reconciliation, then inspect pending targets and channel events. | | active | Expected targets are active, no qualifying active error exists, and renewal is not yet due. | Verify notification and Workflow activity against expected provider events. | | expiring | The earliest active channel is inside its provider-specific renewal window. | Watch renewal events and confirm the state returns to active. | | error | A subscription/provider error, active provision/renew alert, or expired channel exists. | Inspect last_error, alerts, account lifecycle, and provider permissions before retrying. | | fallback | Instant channel reconciliation crossed the configured failure threshold and polling fallback is active. | Confirm polling coverage and latency, fix Instant delivery, then observe the stability window. |

Channel health also exposes expected, active, and pending target counts; expiration; failure count; next retry; last healthy, notification, and reconciliation timestamps; fallback start; and the configured recovery policy.

Operational endpoints

| Endpoint | Purpose | | --- | --- | | GET /v1/sources/channels | List as many as 250 Instant Sources and optionally filter by channel status. | | GET /v1/sources/channel-alerts | List active, resolved, or all alerts, up to 100. | | GET /v1/sources/channel-metrics?days=14 | Aggregate team metrics by day for 1–90 days. | | GET /v1/sources/channel-settings | Read email, Slack, cooldown, and silence settings. | | PATCH /v1/sources/channel-settings | Update alert delivery and silence settings. | | GET /v1/sources/:id/channel-events | Inspect one Source’s channel events, channel rows, and alert-delivery outcomes. | | POST /v1/sources/:id/channel-retry | Request immediate reconciliation for one enabled Instant Source. | | PATCH /v1/sources/:id/delivery | Change between supported instant and polling definitions and configure fallback. | | POST /v1/sources/channels/bulk | Retry or change delivery for as many as 100 Source IDs. |

All protected calls use the active team boundary. See the API reference for examples.

Metrics to interpret

The per-Source model summarizes the current and previous UTC date, presented as metrics_48h:

• channels created and renewed;
• channel creation failures;
• notifications received and queued;
• polling fallback starts and Instant restorations;
• alerts sent; and
• average notification-to-queue latency.

The team metrics endpoint exposes daily series for up to 90 days and can also contain duplicate notifications, stop failures, and notification-silence counts.

Metrics are counters, not a provider delivery guarantee. A zero notification count may mean no matching business event occurred. Compare it with the provider’s event log or an expected-volume signal.

Retry and fallback behavior

After a channel provisioning or renewal failure, FastHook increments failure_count and schedules another reconciliation. The current retry delays are approximately 60, 120, 240, 480, 960, 1,920, and then at most 3,600 seconds.

When automatic fallback is enabled and the failure count reaches max_failures, the runtime changes to polling_fallback. Current configuration bounds are:

• max_failures: 1–20, default 3;
• restore_after_minutes: 1–1,440, default 30; and
• auto_fallback: enabled unless explicitly set to false.

Automatic or manual polling requires a supported polling counterpart for the Trigger. Do not assume every Instant provider definition has equivalent polling coverage.

After reconciliation becomes healthy in fallback mode, FastHook starts a stability window. It restores Instant mode only after the channel remains healthy for restore_after_minutes. The transition records an instant_restored event and metric.

Recover an error channel

1. Confirm the active team, Source ID, provider, Trigger definition, and connected account.
2. Read the channel model and note status, target counts, expiration, last_error, failure count, next retry, and fallback state.
3. Read active alerts and the Source’s channel events. Distinguish provisioning, renewal, stop, silence, and alert-delivery failures.
4. Check connected-account state, scopes, provider membership, selected resources, and whether the provider resource still exists.
5. Reconnect or repair provider access when authorization is the cause.
6. Request POST /v1/sources/:id/channel-retry. It requires an enabled Instant Source with a connected account and returns 202 with status: connecting.
7. Confirm expected targets become active and provision/renew alerts resolve.
8. Produce one controlled provider event and verify notification, Source activity, Workflow run, and provider-side Action result.

Manual retry clears the next scheduled retry and requests reconciliation; it does not recreate a deleted provider resource or grant missing permissions.

Use polling deliberately

Switch to polling when the matching Trigger definition supports it and delayed detection is safer than continued Instant-channel failure. Specify delivery_mode: polling and preserve a reviewed polling schedule. For Instant mode, configure fallback explicitly when the defaults do not match the business risk.

Polling can change latency, provider quota use, cursor behavior, duplicate risk, and the time window in which events appear. Validate the transition with a known event and avoid switching modes repeatedly during an incident without recording the resulting coverage window.

Continue with Workflow monitoring and alerts, Authentication and permissions, and Incident response.