Docs

Guides Overview

Guides are practical workflow pages. They start from a real integration problem and show how FastHook objects fit together: sources receive traffic, connections route branches, destinations receive delivery, and request/event/attempt records explain what happened.

Use this overview as the map for choosing the next guide. Start with a working route, then add trust boundaries, branch-local rules, transformations, local testing, provider patterns, throughput controls, and recovery runbooks.

Guide Map

The guide set is organized around the operational shape of a webhook route. Build ingress first, make each branch explicit, then operate from evidence instead of guessing from provider dashboards or receiver logs.

Most pages reuse the same terms and ids: src_* for sources, conn_* for connections, des_* for destinations, req_* for accepted or rejected ingress, evt_* for branch work, and att_* for receiver delivery attempts.

  • Ingress guides explain source URLs, allowed methods, source authentication, custom provider responses, and accepted request evidence.
  • Routing guides explain connection-local filters, transformations, deduplication, delays, retry, fan-out, fan-in, and provider event routing.
  • Operations guides explain API automation, CLI workflows, environment separation, observability, throughput, pause/resume, replay, and the 200 OK caveat.
  • Trust guides separate inbound provider verification from outbound FastHook delivery signatures.
Choose the guide by the problem you are solving, not by the provider name alone.

Resource Model

The route model is the backbone of the docs. A source owns the public ingress contract. A connection owns one branch from that source to a destination. A destination owns the receiver endpoint, method, auth mode, and delivery capacity.

Keep receiver endpoints unique as destination records. If several connections should deliver to the same receiver URL, reuse the same destination_id and create separate connections to it.

  • Sources: public hook URL, allowed_http_methods, auth_type, auth, custom_response, disabled state, request evidence.
  • Connections: source_id, destination_id, rules, paused_at, disabled_at, branch event evidence.
  • Destinations: receiver URL, HTTP method, auth_type, rate limit, delivery attempt evidence.
  • Requests: accepted or rejected ingress records, including source_id and verified state.
  • Events: branch-local work records, including connection_id, status, retry state, and ignored/held outcomes.
  • Attempts: outbound delivery records, including destination_id, response status, latency, trigger, and failure code.
Resources are configured above the line. Evidence is inspected below the line.

Recommended Reading Order

If you are building a route from zero, read in lifecycle order. If you are debugging production, jump directly to the evidence or recovery guide that matches the symptom.

The sequence moves from first delivery to production operations.
Lifecycle path
1. Receive Webhooks
2. Test Webhooks Locally
3. Source Authentication and Verify Webhooks
4. Connections Guide
5. Filter, Transform, Fan-out, Fan-in
6. Observability, Pause/Resume, Replay
7. Throughput, DDoS, Deduplication, 200 OK caveat

Build And Test

  • Receive Webhooks: create a source, destination, and connection, then inspect request, event, and attempt records.
  • Test Webhooks Locally: use a CLI destination to deliver FastHook traffic to a local app while keeping the provider pointed at FastHook.
  • CLI Connection Management: script source, destination, connection, and recovery workflows with JSON and repeatable commands.
  • API Automation: use api.fasthook.io for resource creation, rule changes, inspection, project secrets, replay, and metrics.
  • Manage Environments: keep production, staging, and local routes separated by source, destination, connection, ids, and secrets.

Secure Trust Boundaries

FastHook has two different trust boundaries. Source authentication protects ingress from the provider into FastHook. Destination delivery signatures let your receiver verify that an outbound delivery came through FastHook.

  • Source Authentication: configure BASIC_AUTH, API_KEY, or HMAC on a source and understand accepted verified=false versus verified=true.
  • Verify Webhooks: compare inbound source verification with outbound FastHook delivery verification.
  • Destination Delivery Signatures: enable FASTHOOK_SIGNATURE on HTTP destinations and verify x-fasthook-signature over timestamp.rawBody.
  • Custom Source Responses: return the provider's expected 2xx body while still keeping request capture and routing semantics clear.
  • Avoid Webhook DDoS: protect the source boundary, connection boundary, destination capacity, and replay operations.

Route And Shape Events

When one source feeds more than one consumer, make each branch a connection. Put filters, transforms, retries, delay, deduplication, and pause behavior on the branch that needs it.

  • Connections Guide: understand one source-to-destination route with branch-local rules and inspection.
  • Filter And Route Events: route by headers, body, query, and path; inspect ignored branch evidence.
  • Transform Webhook Payloads: run JavaScript transformations before attaching them to connection rules.
  • Transform Content-Type: convert JSON, form, text, and content-type behavior deliberately.
  • Deduplication Patterns: suppress repeated branch delivery using include_fields and a time window.
  • Fan-Out Webhooks: deliver one accepted request to multiple destination branches.
  • Fan-In Webhooks: route several sources or connections into one shared destination_id.
  • Provider Event Routing: model Stripe, GitHub, Shopify, Twilio, and internal provider streams without hiding branch ownership.

Operate And Recover

Production work is evidence-first. Start with the request, move to events and ignored events, then inspect attempts and metrics before retrying or replaying anything.

  • Observability Of Event Flows: debug from request to event to attempt and metrics.
  • Pause And Resume Connections: hold one connection branch during receiver maintenance and drain it later.
  • Control Throughput: combine destination rate limits, pause, retry backoff, filters, and replay windows.
  • Webhook Replay Systems: choose request replay, event retry, and bulk operation recovery safely.
  • Why 200 OK Does Not Guarantee Processing: FastHook 2xx means the accepted request is captured and will not disappear, but downstream processing still needs evidence.
  • Avoid Webhook DDoS: keep replay, retry, and bulk recovery scoped so a fix does not become a second outage.

Choose By Symptom

  • Provider cannot reach you: Receive Webhooks, Source Authentication, Custom Source Responses.
  • Local app needs real traffic: Test Webhooks Locally, CLI Connection Management.
  • Provider says 200 but app failed: Why 200 OK Does Not Guarantee Processing, Observability Of Event Flows.
  • Only one consumer should receive the event: Filter And Route Events.
  • One provider event should feed many consumers: Fan-Out Webhooks.
  • Several sources should reach one receiver: Fan-In Webhooks and Provider Event Routing.
  • Receiver cannot handle spikes: Control Throughput, Pause And Resume Connections, Avoid Webhook DDoS.
  • Payload shape does not match receiver: Transform Webhook Payloads and Transform Content-Type.
  • Duplicate work happened: Deduplication Patterns plus receiver idempotency.
  • Need to recover after an outage: Webhook Replay Systems, Observability, and scoped event retry.

Next