How it works

A high-level look at HostWebhook's architecture — from ingress to delivery.

1. Ingress

Each webhook you create gets a unique ingress URL of the form:

https://api.hostwebhook.com/api/in/<token>

Point any webhook source to this URL. HostWebhook accepts HTTP POST requests with any content type and any payload size up to your plan limit. The ingress handler responds with 202 Accepted immediately — it never blocks waiting for your server.

2. Queue

Every accepted event is persisted to the database and pushed into a Redis-backed queue (BullMQ). This decouples ingress latency from delivery latency: your webhook provider always gets a fast response, even if your server is slow or temporarily down.

ℹBecause events are persisted before being queued, they survive restarts and crashes. No events are lost even if the queue worker crashes mid-delivery.

3. Delivery

A queue worker picks up the event and makes an HTTP POST to your target URL, forwarding the original payload and headers plus a few extra HostWebhook headers:

X-HostWebhook-Event-IdUnique ID of the event — use for idempotency
X-HostWebhook-AttemptDelivery attempt number (1 = first try)
X-HostWebhook-Signaturet=<ms>,v1=<hmac-sha256> — sign of timestamp.rawBody
Content-TypeAlways application/json

Your server must respond with a 2xx HTTP status within 30 seconds. Anything else (non-2xx, timeout, connection refused) is treated as a failure and schedules a retry.

4. Retries

Failed deliveries are retried automatically with exponential backoff. The retry schedule for the default 5-retry policy:

Attempt	Delay	Cumulative wait
1st retry	30 seconds	30s
2nd retry	5 minutes	~5m
3rd retry	30 minutes	~35m
4th retry	2 hours	~2h 35m
5th retry	8 hours	~10h 35m

After all retries are exhausted the event is marked failed. You can replay it manually from the dashboard at any time.

5. Monitoring

The dashboard gives you a real-time view of every event and delivery attempt, including HTTP response body, status code, and latency. Events stream in via WebSocket — no refresh needed.

✦All plans include configurable failure alerts — get notified by email when a webhook has repeated delivery failures. Configure them under Alerts in the dashboard.

Security model

Each webhook has two secrets you can rotate at any time from the dashboard:

Ingress token — the unique token in your ingress URL. Anyone with this token can send events to your webhook. Rotate it if the URL is leaked.
Signing secret — used to compute the X-HostWebhook-Signature header on every outgoing delivery. The signature covers timestamp.rawBody to prevent replay attacks. Your server uses this to verify deliveries are authentic.