HookRelay User Guide

Webhook receiver, payload inspector, forwarding with retry, and replay.

1. Enable HookRelay in the Products page

2. Navigate to hooks.microgemlabs.ai

3. Click + New Endpoint to create a webhook receiver

4. Copy the receiver URL and configure it in your webhook source (GitHub, Stripe, etc.)

HookRelay gives you a stable webhook endpoint that logs every incoming request, optionally forwards it to a destination URL with retry logic, and lets you inspect payloads and replay failed deliveries.

• Relay: Point GitHub webhooks at HookRelay, which forwards to your backend. If your backend goes down, HookRelay retries automatically.
• Inspect: Debug webhook payloads from third-party APIs by examining headers, body, and query parameters in the inspector.
• Buffer: Receive webhooks during deployment downtime and replay them after your service is back up.
• Fan-out: Multiple internal services need the same webhook — forward to one, inspect the payload for the others.

Forward & Inspect

Incoming webhooks are logged AND forwarded to your destination URL. If forwarding fails, HookRelay retries with configurable delay. You can inspect the full payload and forward result in the dashboard.

Inspect Only

Incoming webhooks are logged but NOT forwarded anywhere. Use this for debugging — see exactly what a webhook source is sending without needing a running backend.

{"X-Internal-Auth": "secret-token", "X-Source": "hookrelay"}

Each endpoint gets a unique receiver URL:

https://hooks.microgemlabs.ai/api/hook/[uuid]

Configure this URL in your webhook source's settings. HookRelay accepts all HTTP methods (GET, POST, PUT, PATCH, DELETE) on this URL.

What happens on each request:

1. HookRelay captures the full request (method, headers, body, query params, source IP)

2. Returns 200 OK immediately (never blocks the sender)

3. If a forward URL is configured, queues forwarding as a background task

4. The forward task sends the payload to your destination with retry on failure

The endpoint detail page provides a two-panel inspector:

• Body — Query parameters as key=value pairs, request body with auto-formatted JSON
• Headers — All captured headers in key: value format
• Forward Response — The destination server's response body (auto-formatted JSON)

The forward result summary shows HTTP status, duration, attempt count, and error message.

Failed deliveries can be replayed with one click. The Replay button appears on any request with forwardStatus: failed. Replaying:

1. Resets the forward status to "pending"

2. Re-queues the forwarding task

3. HookRelay sends the original payload to the destination again with fresh retry logic

This is useful after fixing a backend issue — replay all the webhooks that arrived during the outage.

When forwarding, HookRelay adds these headers to help your backend identify the source:

Plus any custom headers configured in Forward Headers.

HookRelay fires an on-call alert when 3 or more forward failures occur within 15 minutes for the same endpoint. This prevents alert fatigue from a single failed request while catching persistent issues quickly.

Alerts are deduplicated — only one active alert per endpoint at a time.

Webhook request records are retained for 30 days. A daily cleanup job removes older records. Plan your replay strategy accordingly — requests older than 30 days cannot be replayed.

• Cookie headers are automatically redacted in stored requests
• Auth requirement rejects unauthorized senders at the edge
• Paused endpoints accept requests silently (return 200) but don't store or forward them
• All data is stored in your team's Supabase database — no third-party data sharing

Suppress HookRelay forward failure alerts during planned maintenance (Ops → Maintenance). Webhook reception and forwarding continue normally — only the failure alerting is suppressed. This is useful when your forwarding destination is intentionally offline during a deployment. Scope suppression globally, to HookRelay only, or to a specific endpoint.

Define automated responses to forward failures (Skills → Runbook (/agent/skills?type=runbook)). Example: create a "Restart Forward Target" template that POSTs to your service management API when HookRelay detects persistent forward failures to a specific endpoint. Three trust levels control whether MicroGemAI can execute automatically.

When forward failure patterns resolve, MicroGemAI auto-generates a postmortem with which webhooks failed, error patterns, forward success rate during the incident window, and action items. Review and publish at Ops → Postmortems.