alepha@docs:~/docs/.content/release/framework/docs/guides/features$
cat 2-webhooks.md | pretty
8 min read
Last commit:

#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:

typescript
 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

bash
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 send inside $transactional commits 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, send is not tied to anything you wrote before it. This is the jobs module's rule, see pushing inside a transaction.
  • Any 2xx is a success. 410 Gone unsubscribes 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.test event 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: https only, port 443 (or one listed in webhookOptions.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:

typescript
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.

typescript
 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/events lists every event, its description and the JSON Schema of its data (behind admin:webhook:read, unless webhookOptions.publicCatalog is set before the app starts);
  • the OpenAPI document served by $swagger gains an x-webhooks section, one entry per event: a POST whose body is the envelope with the event's own data schema, and the three webhook-* headers. It is an extension key because the document is OpenAPI 3.0, where the webhooks field 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):

typescript
 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.

typescript
 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:
js
 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 2xx fast 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 Gone to 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:

typescript
 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.