Guide

API Automation

FastHook's dashboard is backed by the same resource model exposed through the public API. Use API automation when routes should be created from deployment scripts, CI jobs, internal tooling, or incident runbooks.

This guide shows how to structure automation around the API base URL, team scoping, resource upserts, connection changes, post-deploy verification, metrics, and recovery commands.

API Surface And Auth

Use the public API for automation. The dashboard proxies the same backend through /api/control, but scripts and CI jobs should call https://api.fasthook.io/v1 directly.

FastHook currently accepts public API paths with or without the /v1 prefix. Keep /v1 in scripts so the API version is visible in logs, runbooks, and CI output.

  • Authenticate with Authorization: Bearer fhp_xxx for a project API key or a session token for user-scoped automation.
  • Pass x-team-id on every automation call when the credential can access more than one team.
  • Project API keys come from GET /v1/project-secrets and work with resource, metrics, retry, and bulk-operation endpoints.
  • List endpoints return pagination metadata, count, and models.
  • Store full secrets in CI secret storage; only print masked values or ids in logs.
Automation should call the public API with a bearer credential and x-team-id so every change is scoped to the intended team.
Authenticated request
curl "https://api.fasthook.io/v1/sources?limit=100" \
  -H "Authorization: Bearer fhp_xxx" \
  -H "x-team-id: tm_xxx"

Upsert A Route From CI

A route script should create or update the source, create or update the destination, then create or update the connection. Keep the returned ids because later metrics, inspections, pauses, retries, and rule updates depend on them.

Use PUT /v1/sources and PUT /v1/destinations for name-based upsert. Use PUT /v1/connections when you have either an id or the source_id plus route name. Use PATCH /v1/connections/:id for focused changes after a route exists.

  • Source upsert returns the public source URL and src_ id.
  • Destination upsert returns the des_ id and normalized delivery config.
  • Connection upsert returns the route id, embedded source and destination objects, paused_at, disabled_at, and normalized rules.
  • Connection ids are opaque. Demo data includes both web_ and conn_ style ids, so scripts should store the returned id.
  • FastHook normalizes connection rules in the order deduplicate, transform, filter, delay, retry.
Build the route in dependency order: source, destination, then connection. Store the returned ids for later operations.
Route upsert sequence
API="https://api.fasthook.io/v1"
TEAM="tm_xxx"
AUTH="Authorization: Bearer fhp_xxx"

# 1. Upsert source.
curl -X PUT "$API/sources" \
  -H "$AUTH" \
  -H "x-team-id: $TEAM" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "stripe-production",
    "type": "WEBHOOK",
    "status": "enabled",
    "config": {
      "auth_type": "HMAC",
      "auth": {
        "secret": "whsec_provider_secret",
        "signature_header": "stripe-signature"
      },
      "allowed_http_methods": ["POST"]
    }
  }'

# 2. Upsert destination.
curl -X PUT "$API/destinations" \
  -H "$AUTH" \
  -H "x-team-id: $TEAM" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "billing-api-production",
    "type": "HTTP",
    "config": {
      "url": "https://api.example.com/webhooks/stripe",
      "http_method": "POST",
      "rate_limit": 60,
      "rate_limit_period": "minute",
      "path_forwarding_disabled": false,
      "auth_type": "FASTHOOK_SIGNATURE",
      "auth": {}
    }
  }'

# 3. Upsert connection with ids returned by the previous calls.
curl -X PUT "$API/connections" \
  -H "$AUTH" \
  -H "x-team-id: $TEAM" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "stripe-production-to-billing-api-production",
    "source_id": "src_xxx",
    "destination_id": "des_xxx",
    "paused_at": null,
    "disabled_at": null,
    "rules": [
      {
        "type": "deduplicate",
        "window": 300000,
        "include_fields": ["body.id"]
      },
      {
        "type": "filter",
        "body": { "type": "invoice.paid" }
      },
      {
        "type": "retry",
        "strategy": "exponential",
        "interval": 30000,
        "count": 5,
        "response_status_codes": ["429", "500-599", "!501"]
      }
    ]
  }'

Patch Without Rebuilding

Automation should be deliberate about replacement semantics. Patch fields when the script owns only part of a resource. Replace only when the JSON file is the complete desired state.

  • PATCH /v1/sources/:id partially updates a source.
  • PATCH /v1/destinations/:id merges destination fields and config.
  • PUT /v1/destinations/:id replaces the destination config; use it only when your file contains the full config.
  • PATCH /v1/connections/:id updates route fields, rules, paused_at, and disabled_at.
  • DELETE /v1/sources/:id, /v1/destinations/:id, and /v1/connections/:id remove the resource.
Patch connection rules
curl -X PATCH "https://api.fasthook.io/v1/connections/conn_xxx" \
  -H "Authorization: Bearer fhp_xxx" \
  -H "x-team-id: tm_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      {
        "type": "retry",
        "strategy": "linear",
        "interval": 60000,
        "count": 3,
        "response_status_codes": ["500-599", "429"]
      }
    ]
  }'

Project Secrets In CI

Project secrets provide two different credentials: the project API key used by automation and the signing secret used for FastHook outbound delivery verification. Keep them separate in runbooks.

GET /v1/project-secrets returns full values. Treat the response as sensitive and avoid logging it outside a secure terminal or secret-management job.

  • Use api_key.value as Authorization: Bearer fhp_xxx for CI jobs.
  • Use signing_secret.value in receivers that verify FASTHOOK_SIGNATURE delivery.
  • POST /v1/project-secrets/rotate with an empty body rotates both secrets.
  • POST /v1/project-secrets/rotate with rotate: ["signing_secret"] rotates only the outbound signing secret.
  • PUT /v1/project-secrets accepts caller-provided api_key and/or signing_secret values.
Project secrets
# Read current masked metadata and full secret values.
curl "https://api.fasthook.io/v1/project-secrets" \
  -H "Authorization: Bearer fhs_xxx" \
  -H "x-team-id: tm_xxx"

# Rotate only the outbound signing secret.
curl -X POST "https://api.fasthook.io/v1/project-secrets/rotate" \
  -H "Authorization: Bearer fhs_xxx" \
  -H "x-team-id: tm_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "rotate": ["signing_secret"] }'

Post-Deploy Verification Gates

Do not stop a deploy script after resource upsert. Send or wait for a test event, then prove the source accepted it, a connection branch was created, delivery was attempted, and metrics are sane for the deployment window.

Use request metrics for ingress questions and event metrics for branch delivery questions. Metrics endpoints require date_range[start] and date_range[end].

  • GET /v1/requests verifies source ingress and exposes events_count.
  • GET /v1/events with connection_id verifies the branch was created and shows status.
  • GET /v1/attempts with event_id verifies destination response details.
  • GET /v1/connections/:id/latest-input returns the latest input available for transformation testing.
  • GET /v1/metrics/events can be filtered by source_id, connection_id, destination_id, status, and batch_operation_id.
Automation should verify ingress, routed events, attempts, latest input, and metrics before it reports success.
Verification queries
curl "https://api.fasthook.io/v1/requests?from=now-15m&source_id=src_xxx&include=data&limit=20" \
  -H "Authorization: Bearer fhp_xxx" \
  -H "x-team-id: tm_xxx"

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

curl "https://api.fasthook.io/v1/connections/conn_xxx/latest-input" \
  -H "Authorization: Bearer fhp_xxx" \
  -H "x-team-id: tm_xxx"

curl "https://api.fasthook.io/v1/metrics/events?date_range[start]=2026-05-29T00:00:00Z&date_range[end]=2026-05-29T23:59:59Z&granularity=1h&connection_id=conn_xxx&measures[]=count&measures[]=delivered_count&measures[]=failed_count" \
  -H "Authorization: Bearer fhp_xxx" \
  -H "x-team-id: tm_xxx"

Incident Automation

Incident scripts should prefer narrow, observable actions. Pause one branch when a receiver is unhealthy, inspect the affected events, retry one event first, then create a bulk operation only when the filter is known to be safe.

Request replay and event retry are different. Request replay queues the stored inbound request through current routing. Event retry retries an existing destination branch and requires the source and connection to be enabled and the connection to be unpaused.

  • PUT /v1/connections/:id/pause holds new delivery for that connection branch.
  • PUT /v1/connections/:id/unpause releases held work.
  • POST /v1/requests/:id/retry replays an inbound request through current routing.
  • POST /v1/events/:id/retry retries one outbound event branch.
  • POST /v1/events/bulk_operations creates event bulk retry from filters.
  • POST /v1/events/bulk_operations/:id/cancel cancels planned or running event bulk retry.
Runbooks should pause narrowly, inspect evidence, retry one event, and only then start bulk retry with a cancel path.
Recovery commands
# Hold one branch.
curl -X PUT "https://api.fasthook.io/v1/connections/conn_xxx/pause" \
  -H "Authorization: Bearer fhp_xxx" \
  -H "x-team-id: tm_xxx"

# Retry one event after the receiver is fixed.
curl -X POST "https://api.fasthook.io/v1/events/evt_xxx/retry" \
  -H "Authorization: Bearer fhp_xxx" \
  -H "x-team-id: tm_xxx"

# Bulk retry only a narrow failed window.
curl -X POST "https://api.fasthook.io/v1/events/bulk_operations" \
  -H "Authorization: Bearer fhp_xxx" \
  -H "x-team-id: tm_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2026-05-29T10:00:00.000Z",
    "to": "2026-05-29T10:30:00.000Z",
    "status": "FAILED",
    "source_id": "src_xxx",
    "connection_id": "conn_xxx",
    "destination_id": "des_xxx",
    "q": "timeout"
  }'

CLI For The Same Flow

Use the CLI when operators need the same automation shape from a terminal. Keep JSON definitions in source control without API keys or signing secrets, and load sensitive values from the environment or secret manager.

  • Use fasthook api when a high-level command wrapper does not exist yet.
  • Store the project API key in CI secrets.
  • Use separate JSON files per environment when URLs, auth, or rate limits differ.
  • Print returned ids and metrics summaries, not secret values.
CLI automation
fasthook sources upsert --json-file source.json
fasthook destinations upsert --json-file destination.json
fasthook connections upsert --json-file connection.json
fasthook events list --connection_id conn_xxx --limit 20
fasthook metrics events --connection_id conn_xxx --from 2026-05-29T00:00:00Z --to 2026-05-29T23:59:59Z

Automation Checklist

  • The script sets API base URL, Authorization, and x-team-id explicitly.
  • Source, destination, and connection JSON are environment-specific.
  • The script stores returned src_, des_, and connection ids.
  • Connection rules are patched intentionally and checked after the API normalizes them.
  • Destination PUT is used only for full replacement; PATCH is used for partial changes.
  • Post-deploy verification checks requests, events, attempts, latest input, and metrics.
  • Bulk operations require a narrow filter, visible progress, and a cancel path.
  • Secrets are rotated from secure runbooks and never printed in CI logs.

Next