Webhooks: Capture & Replay

Two halves: capture vs. replay

Capturing inbound webhooks

Point a provider's webhook at the agent. Each captured request is appended as one line to a per-service JSONL file under the shared data volume (data/webhooks/{service_id}.jsonl). The capture is lossless — method, full request URI (including query string), headers, and the body are all preserved so a downstream HMAC signature still verifies on replay.

# One captured inbound webhook (one JSONL line per request)
{
  "id": "wh_a1b2c3d4e5f60718",
  "received_at": "2026-06-17T09:14:22Z",
  "tenant": "default",
  "service_id": "stripe",
  "method": "POST",
  "uri": "/webhook/default/stripe",
  "headers": { "content-type": "application/json" },
  "body": { "type": "payment_intent.succeeded" },
  "signature_kind": "stripe"
}

Each record carries a short unique id of the form wh_<16 hex> and an ISO-8601 capture timestamp. Capture is best-effort by design: a webhook the agent fails to persist (disk full, permission error) is logged and counted, and the sender still receives a success response so it does not retry. Storage failures increment ghost_io_errors_total{operation} with operation labels like webhook_open, webhook_write, and webhook_mkdir.

Provider detection

On capture, the agent infers a signature_kindfrom the header set — narrower providers win first so a request that happens to carry two providers' headers is tagged by the more specific one:

Detection is read-only: Gostly never verifies a signature for you and never stores a signing secret. The signature_kind only tells the dashboard which timestamp / nonce fields to parse out of the captured header for the detail view.

Binary and non-UTF-8 bodies

UTF-8 payloads (JSON, form-urlencoded, plain text — the common case) are stored as a plain string so the JSONL line stays human-readable and grep-friendly. A body containing non-UTF-8 bytes (protobuf, MessagePack, EDI, a binary frame) is captured byte-for-byte via base64 instead — recorded as {"b64": "…", "size_bytes": N} rather than a string. Preserving the exact bytes is what keeps an HMAC computed over the body valid when the webhook is later replayed.

WebSocket frames: captured, not replayed

When TLS interception is enabled, WebSocket frames are captured for observability into the same per-service store, tagged with a transport marker, a connection id, a direction (client-to-server or server-to-client), and a frame kind (text / binary / ping / pong / close). This is a recording surface only.

Operator-triggered replay

Replay lives entirely in the control-plane API. There is no agent-side scheduler and no fan-out: a captured webhook is re-sent only when an authenticated operator calls the replay endpoint. The control plane reconstructs the original request — same method, same body, same headers (signature header included by default) — and POSTs it to the target URL you supply, then returns the target's response so you can inspect it.

All four endpoints live under /v1/webhooks and require an API key and a tenant. Replay is available on every paid plan — there is no tier gate on webhook playback.

Replaying a capture to a target URL:

curl -X POST \
  http://localhost:8000/v1/webhooks/stripe/wh_a1b2c3d4e5f60718/replay \
  -H "X-API-Key: $GHOST_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "target_url": "http://localhost:4000/webhooks/stripe",
    "preserve_signature": true,
    "timeout_seconds": 10
  }'

# Returns the target's response, e.g.
# { "target_url": "...", "status_code": 200,
#   "response_headers": { ... }, "response_body": "...", "elapsed_ms": 37 }

Replay options

Replay target safety

Replay lets an authenticated tenant POST a captured body to a URL they choose — an SSRF-shaped capability if left open. Every replay target is validated before any socket opens, in layers: scheme, then hostname literal, then port, then the DNS-resolved IPs. Loopback, private (RFC 1918), CGNAT, link-local, and cloud instance-metadata addresses are rejected by default.

For local development against a service on the same host, an operator can relax the private / loopback checks with GOSTLY_ALLOW_LOCAL_REPLAY=1. The scheme and blocked-port guards stay strict regardless.

Tenancy

Each Gostly deployment is single-tenant: the tenant id defaults to default, and one license key gates one stack. Every webhook endpoint scopes its query to the requesting tenant, and a capture owned by a different tenant reads as a 404. Per-tenant Postgres row-level-security policies are defined as defense-in-depth beneath that; isolation in the default configuration comes from the single-tenant deployment model, with RLS as a defined policy layer rather than engine-enforced multi-tenancy.

What is not shipped yet

To set expectations precisely, the webhook surface today is automatic capture plus operator-triggered, manual replay. The following are roadmap and do not exist in the shipped product:

• Scheduled replay — the agent does not fire captured webhooks on a timer or trigger.
• Fan-out — a single capture is replayed to one target per API call; there is no broadcast to many endpoints.
• Re-signing— Gostly forwards the original signature verbatim and never mints a fresh one, so replay is bounded by the provider's freshness window.
• WebSocket replay — WS frames are captured for observability only.