How to Send Webhooks: Every Part You Have to Build

Sending a webhook is one HTTP POST. Sending webhooks to customers in production is a small system: you need to retry what didn't arrive, sign what you send, record what happened, and stop hammering endpoints that are gone. This post lists every part you end up building, what to decide for each, and a minimal Node.js sender you can start from.

The parts

A webhook sender that customers can rely on has these eleven pieces:

1. Endpoint registration and URL validation. Customers register URLs and pick event types. Validation includes SSRF checks so nobody can point you at your own network.
2. Event types. Names like invoice.paid and the catalog of them.
3. Payload shape. How the type, timestamp and data are laid out.
4. Signing. An HMAC (or public-key) signature so receivers can verify the sender.
5. A queue and retries. Decouple sending from your business logic and retry failures with growing delays.
6. Timeouts and success rules. How long to wait and which responses count as delivered.
7. Delivery logs. Status code, response snippet, duration and errors for every attempt.
8. Failure alerts. Tell your team, and the endpoint's owner, when deliveries keep failing.
9. Auto-disable and re-enable. Stop sending to endpoints that have failed for days, and let them come back.
10. Secret rotation. Replace a signing secret without breaking receivers.
11. A customer portal. Let customers manage endpoints, read logs and replay deliveries themselves.

Registration and URL validation

Model endpoints as customer plus URL, with an optional list of event types per URL. At registration, at minimum: accept only https, reject credentials in the URL (user:pass@), reject IP-literal hosts, and reject internal names such as localhost or *.internal. Then check again right before each send that the hostname doesn't resolve to a private address, because DNS answers can change after registration. The SSRF post goes through the full list.

Event types and payload shape

resource.action names (invoice.paid, customer.deleted) let receivers route by prefix. For the body, a type/timestamp/data envelope is easy to consume, and it is what the Standard Webhooks spec recommends. The same spec suggests keeping payloads small, usually under 20 KB.

Signing

Use a scheme receivers already have libraries for rather than inventing one. Standard Webhooks defines:

• Three headers: webhook-id, webhook-timestamp, webhook-signature
• Signed content id.timestamp.body, HMAC-SHA256, base64
• A secret written as whsec_ plus base64 random bytes (the spec recommends 24 to 64 bytes)

The ID is signed so nobody can change the value receivers deduplicate on. The timestamp is signed so an old captured request can't be replayed later. Standard Webhooks explained goes through the reasoning behind each field.

Queue and retries

Sending inside the request that created the event makes your code wait on the customer's server, and loses the event if that server is down. Write the event, enqueue it, and let a worker send. If you write the business row and the event row in the same database transaction (the transactional outbox pattern), you also avoid "saved the order, never emitted the event" (the outbox pattern).

Retry with short delays first and longer ones as failures continue. We covered schedules, jitter and when to give up in designing webhook retries. Keep webhook-id the same across retries; regenerate the timestamp and signature on every attempt.

Timeouts and what counts as success

• Timeout: 10 to 15 seconds is typical. GitHub gives receivers 10 seconds and Shopify 5 (checked on 2026-09-27 in GitHub's and Shopify's docs). Longer timeouts let slow endpoints tie up your workers.
• Success: 2xx only.
• Redirects: Don't follow them. Following a redirect sends the payload somewhere you never validated.

A minimal sender in Node.js

One attempt: sign, send, stop after 15 seconds, don't follow redirects. Uses the built-in fetch (Node 18+) and AbortSignal.timeout.

import { createHmac, randomUUID } from 'node:crypto';

const SECRET = Buffer.from(process.env.ENDPOINT_SECRET!.replace(/^whsec_/, ''), 'base64');

export async function sendOnce(url: string, msgId: string, type: string, data: unknown) {
  const body = JSON.stringify({ type, timestamp: new Date().toISOString(), data });
  const ts = Math.floor(Date.now() / 1000).toString();
  const sig = createHmac('sha256', SECRET).update(`${msgId}.${ts}.${body}`).digest('base64');
  const started = Date.now();
  try {
    const res = await fetch(url, {
      method: 'POST',
      headers: {
        'content-type': 'application/json',
        'webhook-id': msgId,
        'webhook-timestamp': ts,
        'webhook-signature': `v1,${sig}`,
      },
      body,
      redirect: 'manual', // return 3xx as is instead of following it
      signal: AbortSignal.timeout(15_000), // aborts with a TimeoutError
    });
    const head = (await res.text()).slice(0, 1024);
    return { ok: res.ok, status: res.status, head, ms: Date.now() - started };
  } catch (e) {
    return { ok: false, status: null, head: null, ms: Date.now() - started, error: String(e) };
  }
}

// One ID per event, reused on every retry
const msgId = `msg_${randomUUID()}`;

AbortSignal.timeout() returns a signal that aborts with a TimeoutError after the given time (MDN). With redirect: 'manual', Node's fetch hands you the 3xx response itself, so res.ok is false and the attempt counts as failed. The caller logs the result and, on failure, schedules the next attempt.

Delivery logs

Log every attempt. These records answer support tickets and let you show a customer exactly what their server returned.

Set a retention period and delete old records, shorter if payloads contain personal data. What to log for outgoing webhooks goes deeper.

Alerts and auto-disabling

An endpoint that keeps failing costs a worker slot on every retry. Handle it in two stages: pause briefly after a burst of consecutive failures, and disable the endpoint after failures have lasted days. Tell both your team and the endpoint's owner when you disable it; Stripe, for example, emails account owners when webhook deliveries keep failing (Stripe).

Secret rotation

Customers will need to replace secrets, after a leak or on a schedule. Receivers can't switch at the same instant you do, so for a period sign with both the old and new secret and put both signatures in webhook-signature, separated by a space. Stripe lets the old secret stay active for up to 24 hours (Stripe).

Customer portal

As your customer count grows, so do "please change our URL" and "we didn't get the event" tickets. A page where customers register endpoints, read their delivery logs and replay failures removes most of them. If you embed it in your own app, issue short-lived, per-customer links so no customer can see another's data.

Build order

You don't have to ship everything at once:

1. Signing, queued retries, delivery logs
2. Timeouts, redirect handling, URL validation
3. Failure alerts and auto-disabling
4. Secret rotation and the customer portal

Where Webhook Admin fits

Webhook Admin covers parts 1 and 4 through 11 behind an API and a dashboard. You decide the event types and payloads, then call POST /v1/messages with the customer ID, event type and payload.

• Endpoint URLs must be https on port 443 or 8443. IP-literal hosts, internal names and names that resolve to private addresses are rejected, and redirects are never followed.
• Signatures follow Standard Webhooks; after a rotation, messages carry both signatures for 24 hours.
• Retries: by default immediately, 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 10 h (8 attempts, about 28 hours); you can choose the number of retries and the interval per endpoint. The timeout is 15 seconds.
• Every attempt is logged with the status code, the first 1,024 bytes of the response and the duration, and can be replayed from the dashboard or the API.
• Endpoints that fail for five days are disabled automatically, with alerts to Slack, Microsoft Teams, email, a webhook or Chatwork.
• The customer portal is available from the Starter plan.

The getting started guide walks through the setup and pricing lists the plans. If you'd rather not build the retry, logging and alerting parts yourself, you can sign up for free (50,000 messages a month): https://app.webhookadmin.com/signup