How to fan out webhooks to multiple services
To fan out a webhook to multiple services, receive it once at a single endpoint, verify the signature, return a 2xx immediately, and write the event to a queue. A dispatcher then expands it into one delivery per destination, each with its own timeout, retries, and failure log, so one slow service never blocks the others.
This guide covers the receiving side: a provider such as Stripe or GitHub sends one webhook, and several of your systems need it, say billing, a data warehouse, and an on-call Slack channel. The sending side, where your product delivers one event to every customer endpoint subscribed to it, has the same shape with different constraints, and webhook fan-out covers that. The code below uses Node.js, Postgres, and BullMQ on Redis, but the structure carries over to any stack.
Why forwarding from the handler does not work
The first version everyone writes receives the webhook and, inside the same request, POSTs it to each downstream service in a loop. It works in testing and fails the first time one of those services is slow. Providers wait a few seconds for your 2xx (GitHub allows 10, Shopify 5) and count anything slower as a failure. Stripe then retries for up to three days, so every service that already accepted its copy receives the event again. GitHub does not retry repository webhooks at all, so the event is simply gone. Either way, the provider’s view of your endpoint now depends on the health of every service behind it, and an outage in analytics turns into missing payment events.
Step 1: Receive once, store, and enqueue
Give the provider exactly one webhook endpoint. Before responding, it verifies the signature on the raw body, stores the event under the provider’s own ID, and adds one job per interested destination. For Stripe:
const express = require('express');
const Stripe = require('stripe');
const { Pool } = require('pg');
const { Queue } = require('bullmq');
const { destinations } = require('./destinations');
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const db = new Pool();
const connection = { host: 'localhost', port: 6379 };
const queues = Object.fromEntries(
destinations.map((d) => [d.id, new Queue(`deliver-${d.id}`, { connection })]),
);
const app = express();
app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), async (req, res) => {
let event;
try {
event = stripe.webhooks.constructEvent(
req.body, req.get('stripe-signature'), process.env.STRIPE_WEBHOOK_SECRET,
);
} catch {
return res.sendStatus(400);
}
await db.query(
'INSERT INTO events (id, type, body) VALUES ($1, $2, $3) ON CONFLICT (id) DO NOTHING',
[event.id, event.type, req.body.toString('utf8')],
);
const targets = destinations.filter((d) => d.events.includes('*') || d.events.includes(event.type));
for (const dest of targets) {
await queues[dest.id].add('deliver', { eventId: event.id }, {
jobId: event.id,
attempts: 8,
backoff: { type: 'custom' },
removeOnComplete: { age: 7 * 24 * 3600 },
});
}
res.sendStatus(200);
});
app.listen(3000);
Two details make this safe to retry. The insert ignores conflicts, and using the provider’s event ID as the BullMQ jobId means adding a job that already exists is a no-op, so a Stripe retry of an event you already handled is not fanned out twice. And because the enqueue still runs on a conflict, a process that crashed between the insert and the enqueue on the first attempt gets finished by the provider’s retry. Completed jobs are kept for seven days, longer than Stripe’s three-day retry window, so the jobId check has something to compare against. For GitHub, swap the verification for an X-Hub-Signature-256 check and use X-GitHub-Delivery as the ID; the receiving best practices cover the handler itself.
Step 2: Keep routing in a table
Which destination wants which event types is configuration, not code:
exports.destinations = [
{
id: 'billing',
url: 'https://billing.internal.example.com/hooks/stripe',
events: ['invoice.paid', 'invoice.payment_failed', 'customer.subscription.deleted'],
secret: process.env.BILLING_HOOK_SECRET,
concurrency: 10,
},
{
id: 'warehouse',
url: 'https://ingest.warehouse.example.com/stripe',
events: ['*'],
secret: process.env.WAREHOUSE_HOOK_SECRET,
concurrency: 2,
limiter: { max: 50, duration: 1000 },
},
{
id: 'oncall',
url: process.env.SLACK_WEBHOOK_URL,
events: ['charge.dispute.created'],
concurrency: 1,
transform: (e) => ({
text: `Dispute opened on ${e.data.object.charge}: ${e.data.object.amount / 100} ${e.data.object.currency.toUpperCase()}`,
}),
},
];
With this table, a payment_intent.succeeded reaches only the warehouse, while a dispute reaches the warehouse and Slack. In production the table lives in a database, so adding a destination is a row insert rather than a deploy.
Step 3: Deliver each copy from its own queue
One queue per destination is the isolation boundary. With a single shared queue and 20 workers, a destination that hangs until its timeout can occupy all 20, and billing waits behind the warehouse. With a queue each, a broken destination only backs up its own jobs. The worker process shares the db, connection, and destinations setup from step 1:
const crypto = require('crypto');
const { Worker } = require('bullmq');
const schedule = [5, 300, 1800, 7200, 18000, 36000, 36000].map((s) => s * 1000);
function sign(dest, eventId, body) {
if (!dest.secret) return {};
const timestamp = Math.floor(Date.now() / 1000);
const key = Buffer.from(dest.secret.replace(/^whsec_/, ''), 'base64');
const signature = crypto.createHmac('sha256', key)
.update(`${eventId}.${timestamp}.${body}`)
.digest('base64');
return { 'webhook-id': eventId, 'webhook-timestamp': String(timestamp), 'webhook-signature': `v1,${signature}` };
}
for (const dest of destinations) {
new Worker(`deliver-${dest.id}`, async (job) => {
const { rows } = await db.query('SELECT body FROM events WHERE id = $1', [job.data.eventId]);
const raw = rows[0].body;
const body = dest.transform ? JSON.stringify(dest.transform(JSON.parse(raw))) : raw;
const res = await fetch(dest.url, {
method: 'POST',
headers: { 'content-type': 'application/json', ...sign(dest, job.data.eventId, body) },
body,
signal: AbortSignal.timeout(10_000),
});
if (!res.ok) throw new Error(`${dest.id} answered ${res.status}`);
}, {
connection,
concurrency: dest.concurrency,
limiter: dest.limiter,
settings: { backoffStrategy: (attemptsMade) => schedule[attemptsMade - 1] },
});
}
Each request gets a hard 10-second timeout from AbortSignal.timeout, rather than Node’s default, which waits minutes for a response. A failure is retried on the schedule above: 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, then 10 hours twice, eight attempts across about 27 hours with exponential backoff flattened at the end. A job that exhausts them stays in that queue’s failed set, which serves as the destination’s dead-letter queue: queue.getFailed() lists them and job.retry() replays one once the destination is fixed. The warehouse’s limiter caps it at 50 deliveries a second, a per-destination rate limit that stops a backlog from flattening it when it recovers.
Retries can duplicate and reorder deliveries, so every destination should be idempotent on webhook-id, which carries the provider’s event ID through every attempt. That ID is also why the copies are re-signed. Destinations cannot verify the provider’s original signature once a transform has changed the payload, and they should not each carry every provider’s verification code. Signing with one secret per destination under the Standard Webhooks scheme means every internal service verifies the same way. Slack’s incoming webhook URL is itself the credential, so the oncall destination has no secret and goes out unsigned.
Step 4: Transform per destination when you need to
A Slack channel wants a short message, not a Stripe event object, which is what the transform on the oncall row does. Keeping transforms at the destination level, applied by the worker just before it sends, means the stored event stays the raw original and a bad transform breaks one destination instead of all of them. The same hook handles the format mismatches behind errors like a GitHub to Discord 400.
Build it or use a gateway
Written out, the parts are an endpoint with signature verification, an event store, a routing table, a queue per destination, workers with retries and dead-lettering, and a log of every attempt. Any queue works for the middle: SQS, RabbitMQ, and Redis streams all fit, and the DLQ redrive guide covers getting failed deliveries back out. A webhook gateway is this same architecture packaged as a product. Svix Ingest gives you one URL per source, verifies signatures for providers like Stripe, GitHub, and Shopify, stores every event, and filters, transforms, and fans out to multiple destinations with retries, so the fan-out becomes configuration rather than a service you run.
Frequently asked questions
Can I fan out a webhook by forwarding it from my handler?
Only for a prototype. The provider waits a few seconds for your response, so any slow destination fails the whole delivery, and a provider retry re-sends to destinations that already succeeded. Acknowledge first, queue the event, and deliver each copy from a worker.
Do I need to sign fanned-out webhooks?
Yes, whenever destinations are reachable over a network. Sign each copy with a secret per destination using HMAC-SHA256 and the Standard Webhooks headers, so internal services verify one scheme instead of one per provider.
How is fan-out different from a webhook proxy?
A webhook proxy forwards each request to one destination, usually adding verification and buffering. Fan-out expands one received event into independent deliveries to several destinations, each with its own retries, rate limit, and delivery log.