HookStead documentation

HookStead sits between the services that send you webhooks and the endpoints that handle them.

1. Create an account with your email address and a password, then click the link in the verification email.
2. Create an organization: a name and a URL (e.g. acme). You become its owner, and a Production workspace is created for you.
3. The workspace page shows a Get started checklist. It ticks itself off as you go and disappears once your first delivery succeeds.

1. Sources → enter a name → Create source. Copy the URL it shows.
2. Send something to it, or use Send a test event on the checklist:

curl -X POST "https://<your Hookstead>/in/<source token>"   -H 'content-type: application/json'   -d '{"type":"order.paid","id":"ord_123"}'

3. Destinations → your endpoint's name and URL → Create destination. Copy the signing secret now: it's shown once.
4. On the destination's page, pick the source and Connect source.
5. Send another event. It arrives at your endpoint, and the delivery shows as succeeded.

A source URL looks like https://<your HookStead>/in/<token>. Anything after the token is kept as the event's path, so one source can take /in/<token>/orders and /in/<token>/refunds. On the source's page you can disable it (requests then get 404) or rotate the URL if it leaked; rotating stops the old URL immediately. It also shows the methods the source accepts (POST by default) and the status it answers with (202 by default); change those through the API.

The sources list shows each source's status: Receiving (events in the last 24 hours), Quiet (nothing for longer), Rejecting (its latest request, within the hour, failed verification; usually a wrong or rotated secret), Paused or Waiting for first event. Next to it are the last 24 hours: events per hour, delivery success and rejected requests.

A new source's page waits for its first event and updates by itself when it arrives. Each source page also breaks down the last 7 days by event type (for example invoice.paid, read from the field each provider uses) and lists the last 50 rejected requests with the reason, such as a missing header, a timestamp outside the allowed window, or a signature that doesn't match. Bodies of rejected requests are never stored.

When you create a source, first pick the provider: Stripe, PayPal, Lemon Squeezy, QuickBooks, Shopify, HubSpot, GitHub, GitLab, Linear, Vercel, AWS SNS, Docker Hub, OpenAI, Clerk, Supabase or Standard Webhooks. HookStead then sets up verification for that provider and shows its setup steps, so you only paste the secret. Choose Custom / other to pick the method yourself under Verify requests with. Requests that fail get 401 and are never stored. Signatures are compared in constant time.

Step-by-step setups: Stripe, GitHub.

Senders retry, so the same webhook can arrive twice. Set Dedupe header (optional) to a header that is unique per webhook (GitHub: X-GitHub-Delivery). A repeat is answered with 200, "duplicate": true and the original event's id, and isn't stored or delivered again. Through the API you can dedupe on a JSON field instead (e.g. $.id for Stripe).

What you see in the dashboard is a copy with sensitive values replaced by [redacted]: headers such as authorization, cookie and anything containing signature, token or secret, and body fields such as password, card_number, cvv and iban. Add your own patterns per source through the API (redactionRules).

The original request is stored encrypted and forwarded unchanged. Admins can open it with Reveal original; every view is recorded in the audit log.

A destination needs a Name and an HTTPS URL. Optional settings: the Method, the Timeout (seconds) (15 by default, up to 60), Max attempts (capped by your plan), extra headers (stored encrypted, masked in the dashboard), and how many deliveries may be in flight at once (10 by default).

Connect sources from the destination's page. A connection can be disabled without deleting it; new events then aren't delivered there.

Any 2xx answer counts as delivered. Anything else (or no answer within the timeout) is retried with exponential backoff with jitter: the first retry comes within about 30 seconds, and the wait can double with each attempt, up to 6 hours between attempts. A Retry-After header from your endpoint is honored.

• 4xx answers (except 408 and 429) are final unless you turn on retrying them: they usually mean the request itself is wrong.
• 410 Gone stops retries and flags the destination.
• After the last attempt the delivery is failed (dead). You can retry it any time.

Every attempt carries three headers your endpoint should check:

import { createHmac, timingSafeEqual } from "node:crypto";

// secret: your destination's signing secret ("whsec_…")
// headers: the request headers; rawBody: the body as received (a Buffer), before JSON.parse
export function verifyHookstead(secret, headers, rawBody, toleranceSec = 300) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (!id || !timestamp || !signatures) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSec) return false;

  const key = Buffer.from(secret.slice("whsec_".length), "base64");
  const expected = createHmac("sha256", key)
    .update(`${id}.${timestamp}.`)
    .update(rawBody)
    .digest();
  return signatures.split(" ").some((entry) => {
    const [version, sig] = entry.split(",");
    const given = Buffer.from(sig ?? "", "base64");
    return version === "v1" && given.length === expected.length && timingSafeEqual(given, expected);
  });
}

The scheme is Standard Webhooks, so any Standard Webhooks library works. Complete receivers for Node.js, Python and Go: Verify signatures.

1. On the destination's page, choose how long the old secret keeps signing (Keep the old secret signing for) and Rotate signing secret. The new secret is shown once.
2. During that time every delivery carries two signatures, old and new. Update your endpoint to the new secret whenever it suits you.
3. When the overlap ends, only the new secret signs.

Pause deliveries holds new deliveries instead of sending them, for example during a maintenance window. Resume deliveries sends everything that was held. Deleting a destination cancels its pending deliveries.

Events lists everything received, newest first. Filter by text anywhere in the body or headers, by source, by a header (x-shop: shop-7), by a JSON value ($.data.object.customer=cus_42), by time range, or by delivery outcome (e.g. only events with a failed delivery). Deliveries lists every delivery, filterable by status, error type, HTTP status and source.

Open a delivery to see every attempt: when it ran, what triggered it (first try, automatic retry, manual retry or replay), the request that was sent, and the response: status, headers, the start of the body, and how long it took. Errors are named (TIMEOUT_RESPONSE, HTTP_5XX, CONNECTION_REFUSED, …) so you can filter by them.

A double click never sends twice: each of these carries an idempotency key. Replays are rate limited per organization and per person.

Each destination shows a health status, from its last 15 minutes:

Metrics shows events received, delivered and failed attempts, the success rate and p95 latency for the last 24 hours, 7 days or 30 days. Each chart has a table view.

Alerts → Create alert rule. Alerts are emailed to members of your organization you pick.

You get one email when an incident opens and one when it resolves (after 3 quiet minutes). A quiet period stops repeat emails for an endpoint that keeps flapping. Acknowledge an incident to show your team someone is on it.

Invite people under Settings → Members → Send invite. Invitations are single-use, valid for 7 days, and only work for the invited email address.

Settings → Workspaces. Use one per environment, so test traffic never mixes with production. Members and roles apply to all workspaces of the organization. Deleting a workspace deletes its sources, destinations and events.

Settings → API keys. A key belongs to the organization, has a role (up to Admin), and can expire after 1 to 365 days. It's shown once; we store only a hash. Revoking takes effect immediately. Keys can never manage keys, members or billing.

Settings → Audit log (admins) records security-relevant changes: members and roles, API keys, secrets, views of original requests, retries and replays, billing, and deletions, with who did it and from where.

Prices are on the pricing page. Events older than your plan's retention are deleted automatically.

Settings → Billing shows this month's usage: each webhook received counts once, however many attempts its deliveries take; each replayed delivery counts once more. Owners get an email at 80% and 100%. At 100%, new webhooks are answered with 429 and Retry-After until the month resets (on the 1st, UTC). Senders retry 429s, so upgrading lets them through.

• Upgrade: Settings → Billing → Upgrade to Pro or Upgrade to Team, monthly or yearly. Checkout is handled by Stripe; the new limits apply as soon as the payment is confirmed.
• Change, cancel, update your card or download invoices: Manage billing opens Stripe's customer portal.
• Downgrades and cancellations take effect at the end of the period you paid for. Nothing is deleted, but you can't create more than the new plan allows.
• A failed payment keeps your plan for 7 days while you update your card.

Only owners can change billing.

• Base URL: https://<your HookStead>/api/v1. Authenticate with Authorization: Bearer hw_live_….
• Errors are application/problem+json with a stable code (validation_failed, plan_limit_reached, quota_exceeded, …). Another organization's resources always answer 404.
• Retry, replay, bulk retry and checkout require an Idempotency-Key header: the same key and body return the stored response for 24 hours.

curl https://<your Hookstead>/api/v1/me   -H "authorization: Bearer hw_live_…"

Every endpoint, with its parameters and rules: API reference. The OpenAPI 3.1 description for code generators is at /api/openapi.json.