#Webhooks
Outbound webhooks: your app tells other systems that something happened, with
a signed POST to a URL they gave you, retried until they answer.
Events are declared in code with $webhook. Who receives them is data: rows
an operator manages from the admin. A delivery is a job with a log you can
read when a customer says "we never got it".
#Declare and send
Register AlephaApiWebhooks (it brings alepha/api/jobs), declare an event,
and call send:
1import { $inject, Alepha, z } from "alepha"; 2import { $webhook, AlephaApiWebhooks } from "alepha/api/webhooks"; 3 4class OrderWebhooks { 5 paid = $webhook({ 6 name: "order.paid", 7 description: "An order was paid in full.", 8 schema: z.object({ orderId: z.uuid(), total: z.number() }), 9 });10}11 12class Checkout {13 webhooks = $inject(OrderWebhooks);14 15 async onPaid(orderId: string, total: number) {16 await this.webhooks.paid.send({ orderId, total });17 }18}19 20const alepha = Alepha.create().with(AlephaApiWebhooks).with(Checkout);
send validates the data against the schema, then writes one delivery and
pushes one job for every active endpoint subscribed to order.paid. With no
endpoint listening it writes nothing. An event name is dotted and lower case,
and unique in the app: receivers subscribe to it by name.
#What a receiver gets
POST https://example.app/hooks
content-type: application/json
webhook-id: 0192e4c4-0000-7000-8000-0000000000e1
webhook-timestamp: 1794200000
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
{"id":"0192e4c4-0000-7000-8000-0000000000e1","type":"order.paid","timestamp":"2026-11-09T10:00:00.000Z","data":{"orderId":"...","total":89}}
The signature follows the Standard Webhooks specification, so a receiver in any language can use an existing library.
#Guarantees
Say these to anyone who builds a receiver, before they assume others:
- At least once. A delivery can arrive twice; receivers deduplicate on
webhook-id, which stays the same across retries and redeliveries. - Unordered. Two events can arrive in either order.
- Retried for about a day. Eight attempts with full jitter: each wait is random under a ceiling of 2 minutes, 8 minutes, 32 minutes, 2 h 08, 8 h 32, then 18 hours twice, so a failing delivery keeps trying for 24 hours on average and 48 at most. On Workers without a queue, a retry is never sooner than the 15 minute sweep.
- Inside a transaction, a true outbox. On Postgres and SQLite a
sendinside$transactionalcommits with your write and is delivered right after the commit; a rollback sends nothing. On D1 there is no transaction, so each write stands alone. Called outside a transaction,sendis not tied to anything you wrote before it. This is the jobs module's rule, see pushing inside a transaction. - Any
2xxis a success.410 Goneunsubscribes the endpoint at once. Anything else, a redirect included (none is followed), is a failed attempt.
#The admin
Registering the module adds a Webhooks page to AdminRouter (System
group), behind admin:webhook:read and admin:webhook:write:
- the endpoints, their status, last success and how long they have been failing; create one, pause and resume it, rotate its secret, delete it;
- an endpoint's delivery log: what was sent, what the receiver answered (the status and the first 2 KB of the body), how long it took;
- Redeliver, which sends a delivery again as a new delivery with the same
webhook-id; - Send test event, which delivers a
webhook.testevent to one endpoint and shows the answer.
Pausing stops new deliveries: events sent while an endpoint is paused are
skipped, and the deliveries already in flight leave when it is resumed. The
module disables an endpoint by itself when the receiver answers 410,
when it keeps failing for five days (decided on a fresh failure, so an
endpoint with little traffic is not disabled for one bad day), or when its
secret can no longer be read. A disabled endpoint receives nothing until an
operator enables it again.
#Secrets
Each endpoint has its own signing secret, whsec_ and 32 random bytes. It is
shown once, when the endpoint is created and when its secret is rotated,
and never again: the admin shows its first characters only.
Rotation keeps the old secret signing beside the new one for 24 hours, so
the receiver can deploy the new one without losing a delivery: during the
overlap the webhook-signature header carries two signatures. After a leak,
rotate with expireNow to drop the old one at once.
Secrets are stored encrypted with APP_SECRET. A changed or lost
APP_SECRET makes every stored secret unreadable: each endpoint is then
disabled with reason secret on its next delivery, needs a rotation, and each
receiver needs its new secret. Keep APP_SECRET the way the
crypto guide says.
#Where deliveries may go
A webhook sender makes requests to URLs somebody typed into a form, so the destination is checked when an endpoint is registered or its URL edited, and again before every delivery.
- Everywhere: no credentials in the URL and no fragment. In production:
httpsonly, port 443 (or one listed inwebhookOptions.allowedPorts), and no private, loopback, link-local or local destination written as an address (10.0.0.5,[::1],169.254.169.254, in any spelling) or as a local name (localhost,*.local,*.internal, a name without a dot). No redirect is followed. - On Node and Bun: before each delivery the host is also resolved, and every address it answers is tested, so a public name pointing at a private address is refused. A refusal is a failed attempt, retried, since a DNS record can be fixed.
- On Workers: there is no resolver, so only the written host is tested.
- The limit. The check and the request resolve the name separately. A resolver under an attacker's control can answer the check with a public address and the request with a private one (DNS rebinding), and this does not stop it. An app that lets its own customers register URLs, and runs where private services are reachable, should weigh that before exposing the scoped API below.
Outside production none of the address and port rules apply, so an endpoint
can point at http://localhost:3000 while you develop. An app that delivers
inside its own network in production sets allowPrivateDestinations:
1import { Alepha } from "alepha";2import { AlephaApiWebhooks, webhookOptions } from "alepha/api/webhooks";3 4const alepha = Alepha.create().with(AlephaApiWebhooks);5alepha.store.set(webhookOptions, {6 ...alepha.store.get(webhookOptions)!,7 allowPrivateDestinations: true,8});
A payload larger than 256 KB (maxPayloadBytes) fails send before anything
is written.
#Offering webhooks to your own customers
An endpoint can carry a scope, your own tenancy key (an organization id, a
project id). The rule is fail-closed: an event sent with a scope reaches
the unscoped endpoints and the endpoints of exactly that scope; one sent
without reaches the unscoped ones only. A scoped endpoint never receives an
event sent without its scope, so forgetting scope delivers to your own
endpoints, never to another tenant's.
1import { $inject, z } from "alepha"; 2import { 3 createWebhookEndpointSchema, 4 WebhookEndpointService, 5 webhookEndpointQuerySchema, 6 webhookEndpointResourceSchema, 7 webhookEndpointWithSecretSchema, 8} from "alepha/api/webhooks"; 9import { $secure } from "alepha/security";10import { $action } from "alepha/server";11 12class CustomerWebhooksController {13 endpoints = $inject(WebhookEndpointService);14 15 list = $action({16 method: "GET",17 path: "/my/webhooks",18 use: [$secure()],19 schema: {20 query: webhookEndpointQuerySchema,21 response: z.page(webhookEndpointResourceSchema),22 },23 handler: ({ query, user }) =>24 this.endpoints.find(query, { scope: `customer:${user.id}` }),25 });26 27 create = $action({28 method: "POST",29 path: "/my/webhooks",30 use: [$secure()],31 schema: {32 body: createWebhookEndpointSchema,33 response: webhookEndpointWithSecretSchema,34 },35 handler: ({ body, user }) =>36 this.endpoints.create(body, {37 scope: `customer:${user.id}`,38 userId: user.id,39 }),40 });41}
Every operation of WebhookEndpointService (get, update, pause, resume,
rotate, delete, the delivery log, redeliver, the test event) takes the same
{ scope }, and a row of another scope is not found. Send with the matching
scope: send(data, { scope: "customer:42" }). The framework ships no
customer-facing screen for this yet.
#The event catalog and the OpenAPI document
Your integrators' reference is generated from the $webhook declarations,
not written by hand:
GET /api/webhooks/eventslists every event, its description and the JSON Schema of its data (behindadmin:webhook:read, unlesswebhookOptions.publicCatalogis set before the app starts);- the OpenAPI document served by
$swaggergains anx-webhookssection, one entry per event: aPOSTwhose body is the envelope with the event's owndataschema, and the threewebhook-*headers. It is an extension key because the document is OpenAPI 3.0, where thewebhooksfield does not exist yet (it arrived with 3.1).
#Being told when an endpoint is disabled
Every automatic disable emits webhooks:endpoint:disabled, with the
endpoint's id, host, scope and the reason (gone, failing or secret):
1import { $hook } from "alepha"; 2 3class WebhookAlerts { 4 onDisabled = $hook({ 5 on: "webhooks:endpoint:disabled", 6 handler: (event) => { 7 console.warn(`Webhooks to ${event.host} disabled: ${event.reason}`); 8 }, 9 });10}
To email the user who registered the endpoint, register the notice too (it
needs alepha/api/notifications): alepha.with(WebhookNotifications).
#Testing
Under test the module delivers through MemoryWebhookTransport: nothing
leaves the process, every request is recorded, and the signature is real, so
you can verify it.
1import { Alepha } from "alepha"; 2import { AlephaApiWebhooks, MemoryWebhookTransport } from "alepha/api/webhooks"; 3 4const alepha = Alepha.create().with(AlephaApiWebhooks); 5await alepha.start(); 6const transport = alepha.inject(MemoryWebhookTransport); 7 8// Script a receiver that fails twice, then answers 200. 9transport.respondOnce("https://example.app/hooks", { status: 500 });10transport.respondOnce("https://example.app/hooks", { status: 500 });11 12// ... register an endpoint, send an event ...13transport.wasDelivered("order.paid", "https://example.app/hooks");14transport.lastEnvelope("order.paid");
failNetwork(url) plays an unreachable receiver. A spec that needs real HTTP
substitutes HttpWebhookTransport.
#For the integrator who receives them
This section is written to the receiver; copy it into your own docs.
- Verify the signature over the raw body, the bytes you received, before parsing it: a parsed and re-serialised body is not the same bytes. The scheme is Standard Webhooks, so your language likely has a library. Without one, it is twenty lines:
1import { createHmac, timingSafeEqual } from "node:crypto"; 2 3export function verifyWebhook(secret, headers, rawBody) { 4 const id = headers["webhook-id"]; 5 const timestamp = headers["webhook-timestamp"]; 6 const signatures = headers["webhook-signature"]; 7 if (!id || !timestamp || !signatures) return false; 8 if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false; 9 const key = Buffer.from(secret.slice("whsec_".length), "base64");10 const expected = createHmac("sha256", key)11 .update(`${id}.${timestamp}.${rawBody}`)12 .digest();13 return signatures.split(" ").some((part) => {14 const [version, value] = part.split(",");15 if (version !== "v1" || !value) return false;16 const actual = Buffer.from(value, "base64");17 return (18 actual.length === expected.length && timingSafeEqual(actual, expected)19 );20 });21}
- Reject a timestamp more than five minutes away from your clock, as above: it stops a replayed request.
- Answer
2xxfast and do the work afterwards. Anything else, or no answer within 15 seconds, is retried. - Deduplicate on
webhook-id: the same event can arrive more than once. - Answer
410 Goneto unsubscribe: the sender disables your endpoint.
#Receiving webhooks in an Alepha app
WebhookVerifier from alepha/security verifies a Standard Webhooks request,
from an Alepha app or any other sender, without the webhooks module. Declare
the route without schema.body, so the bytes arrive unread, and outside
/api, which is the actions' namespace:
1import { $env, $inject, z } from "alepha"; 2import { WebhookVerifier } from "alepha/security"; 3import { $route } from "alepha/server"; 4 5class IncomingWebhooks { 6 env = $env(z.object({ ORDERS_WEBHOOK_SECRET: z.text() })); 7 verifier = $inject(WebhookVerifier); 8 9 orders = $route({10 method: "POST",11 path: "/hooks/orders",12 handler: async (request) => {13 const event = await this.verifier.verifyRequest(request, {14 secret: this.env.ORDERS_WEBHOOK_SECRET,15 });16 // event.id, event.type, event.data17 return "ok";18 },19 });20}
A request that fails verification is refused with
InvalidWebhookSignatureError, a 401. secret also takes an array, for a
sender rotating its secret.