Guide

Alerts

Alerts is the operational view for webhook traffic that needs attention. It combines request metrics, event metrics, failed and held events, and recent destination attempts.

Use this page when failed events spike, requests are being rejected, connections are held, or a receiver is returning errors.

The dashboard page is backed by product-visible Control API resources: metrics, events, attempts, and request trace.

Alert Signals

FastHook alert signals are derived from stored request, event, and attempt evidence. They are not opaque log messages; every count should lead to a record that can be inspected.

The dashboard shows failed events, held events, queued events, rejected requests, and recent failed attempts for a selected time window. These are the first signals to check during an incident.

  • Failed events: destination delivery, transformation, or connection processing reached a failed state.
  • Held events: a paused connection or hold state is preventing delivery until resumed.
  • Queued events: events waiting for delivery or retry work.
  • Rejected requests: source method, auth, signature, disabled source, or validation failures.
  • Failed attempts: receiver responses, network failures, or destination errors recorded for outbound delivery.
  • Recent failed and held event lists link back to request trace so one record can be followed end to end.

Why Alerts Use Events And Attempts

FastHook keeps customer-facing delivery evidence in requests, events, attempts, and event data. The Alerts dashboard uses those records because they are already scoped by team, searchable through the Control API, and connected to retry and replay workflows.

Internal error buckets and dead-letter queue archives are infrastructure runbook data. They can help FastHook operators diagnose worker failures, but they are not the public product model for customer alerting.

  • Requests explain source acceptance or rejection.
  • Events explain routing, hold state, retry state, and final delivery state.
  • Attempts explain each outbound delivery response, latency, error code, and response body.
  • Trace connects one inbound request to its events, transformations, attempts, and receiver responses.
  • Operator-only dead-letter archives should be converted into event or attempt state before becoming customer-facing alert evidence.

Dashboard Workflow

  • Open Alerts in the FastHook dashboard.
  • Choose the time window that matches the incident.
  • Check failed, held, queued, and rejected counts.
  • Inspect recent failed attempts to see receiver HTTP status, error code, response body, and requested URL.
  • Open recent failed or held events and jump to request trace.
  • Fix the root cause before retrying or replaying traffic.

API Workflow

Alerts can be automated through the same Control API endpoints used by the dashboard. Start with metrics to detect a spike, list failed events or attempts for evidence, then open request trace when one record needs full context.

Inspect alert evidence
curl "https://api.fasthook.io/v1/metrics/events?from=now-1h&to=now&granularity=5m&measures[]=failed_count&measures[]=hold_count&measures[]=queued_count" \
  -H "Authorization: Bearer fhp_xxx" \
  -H "x-team-id: tm_xxx"

curl "https://api.fasthook.io/v1/attempts?status=FAILED&from=now-1h&to=now&order_by=created_at&dir=desc" \
  -H "Authorization: Bearer fhp_xxx" \
  -H "x-team-id: tm_xxx"

Recovery Decisions

Do not treat every alert the same way. Failed destination attempts, held events, and rejected source requests point to different recovery paths.

  • For failed destination attempts, inspect the receiver response and retry the event only after the receiver or destination config is fixed.
  • For held events, resume the paused connection when the receiver is ready to drain traffic.
  • For rejected requests, fix source auth, provider signature configuration, allowed methods, or disabled source state.
  • For queued events, check destination rate limits, retry schedule, connection pause state, and receiver capacity.
  • For repeated failures across one destination, fix the destination config or receiver before bulk retrying.

Operational Guardrails

  • Prefer one-record trace inspection before bulk retry or replay.
  • Do not retry failed events until the destination issue is understood.
  • Keep receiver response bodies visible in attempts, but avoid copying secrets into downstream error messages.
  • Use time-windowed metrics to detect spikes before opening many individual records.
  • Document whether a recovery used event retry, request replay, pause/resume, or destination config changes.

Next