Webhooks

The diagram shows the three properties the package adds to a plain fetch(): the message exists only if the transaction commits, the work after the commit survives a crash because it is a stored delivery, and every attempt is recorded.

Receiving is a different, much shorter path: the route is guarded by @VerifyWebhook(name), which runs before the handler.

Where this sits in the request lifecycle: sending is not part of any request, because the worker is a background process of the application (disable it per instance with the worker.enabled option). Receiving is part of the route’s pipeline: the decorator verifies before the handler runs, so what the handler receives has already been authenticated. See Request lifecycle for the general order of guards, interceptors and pipes.

Source: Webhooks, "Installation".

The package’s peer dependencies are @nestjs/common and @nestjs/core 12, @nestjs/outbox (0.0.1 or 0.1.0), reflect-metadata and RxJS 7. Outgoing webhooks are outbox messages and incoming ones are deduplicated with the outbox’s inbox, so the application runs the outbox too. Receiving works without outgoing: a service that only receives webhooks still imports OutboxModule for its inbox (see A service that only receives).

The official tutorial runs on PostgreSQL through Drizzle ORM and @nestjs/drizzle, with the pg driver. The page keeps that choice, and notes what changes with TypeORM and with MySQL. Node.js 20.19 or newer is required by the package itself.

WebhooksModule and OutboxModule are registered once, in the root module. Both are global, so Webhooks, WebhookEndpoints, WebhookDeliveries, WebhooksEvents and WebhooksStorage can be injected anywhere. Options come from ConfigService (see Configuration), so a missing secret stops the application at startup instead of at the first request:

Source: Webhooks, "Register the modules".

WebhooksModule needs the outbox: dispatch() is an Outbox.add(), and the fan-out that turns a committed message into deliveries is an outbox handler. Without OutboxModule, startup fails and says so. The most useful options:

Durations are milliseconds or strings such as '15s', '24h' or '5d'. The top-level forRoot() / forRootAsync() options also include outgoing (false for a service that only receives), imports (modules a transport class injects from) and isGlobal (default true). The options' injection token is WEBHOOKS_MODULE_OPTIONS.

Because shutdown must let the relay and the worker finish what they started, enable the shutdown hooks and create the application with the raw body kept (the verifier needs it):

Source: Webhooks, "Register the modules" and Raw body. See Lifecycle events and shutdown for what enableShutdownHooks() does.

The package keeps the endpoints (with their secrets), the messages it dispatched, their deliveries and the log of every attempt in a store, which it reads through two contracts, WebhookEndpointStore and WebhookDeliveryStore. Until you register one, the module keeps everything in memory: fine for a first run, but a restart loses every pending delivery and two instances do not share them. With NODE_ENV=production and no store registered, startup fails unless allowInMemoryStorage: true accepts that (the test run confirmed the production guard: the failure message names allowInMemoryStorage).

On PostgreSQL, register PostgresWebhookStore from @nestjs/webhooks/postgres, next to the outbox’s PostgresOutboxStore from @nestjs/outbox/postgres (the outbox carries dispatched messages out of your transaction and keeps the inbox that deduplicates incoming ones). They are ordinary providers, registered once in the root module, created with a factory that injects the database and the package’s storage registry:

Source: Webhooks, "Keep webhooks in your database".

The executor is how the store reaches the database. fromDrizzle(db) runs the store’s statements through a Drizzle database, whichever driver it uses (the example ran on PGlite). The package also exports fromPg(pool), fromTypeOrm(dataSource), fromPrisma(prisma) and fromKysely(db) for a node-postgres pool, TypeORM, Prisma and Kysely, and fromMysql2(pool) on MySQL. Each executor has its own transaction object, which dispatch() and processInTransaction() then take:

With TypeORM, TypeOrmModule replaces DrizzleModule and the factories inject the DataSource (new PostgresWebhookStore({ executor: fromTypeOrm(dataSource) }, webhooksStorage)), and the service injects Webhooks<EntityManager>. The outbox’s store refuses the database itself (or dataSource.manager), whose statements would commit on their own, so the transaction handle is mandatory. On MySQL 8.4 or 9.x the stores come from @nestjs/webhooks/mysql and @nestjs/outbox/mysql (MySqlWebhookStore, MySqlOutboxStore); MySQL has no schemas inside a database, so the tables keep the schema name as a prefix (nest_webhooks_endpoints, nest_outbox_messages), and the stores refuse MariaDB and a non-strict sql_mode.

The tables the webhook store creates, in the nest_webhooks schema:

Migrations are versioned and the stores apply them themselves at startup (the migrate store option defaults to true, except with NODE_ENV=production, in one transaction under an advisory lock). In production, apply them before the new version of the application starts, from the deploy step, with the package’s command lines (they read DATABASE_URL, or --url, and need pg installed):

Source: Webhooks, "Keep webhooks in your database". The sql command and its flags are listed by npx nest-webhooks --help (for example sql --statement-breakpoints); migrate and status need a database server.

With migrate off, a store whose schema is behind fails the startup (and every call) with a WebhookSchemaError. There are no down migrations. On PostgreSQL the stores rely on READ COMMITTED, the default isolation level, and check it at startup.

A partner subscribes through your API with a URL, the event types it wants and a description. The controller below is a thin layer over WebhookEndpoints. Every call passes the partner’s id as the tenant: the endpoint is created for that tenant, listed for that tenant, and another partner’s endpoint id behaves as if it did not exist. In the example the partner id comes from a header, as a stand-in for a guard that authenticates an API key or a token (see Authentication and Guards):

Source: Webhooks, "Let partners subscribe". The DTOs are plain class-validator classes (url as a string, eventTypes as an array of strings), because the package checks the URL and the types itself; see Pipes and validation. The official page shows every DTO a second time as a Zod schema with @Body({ schema }) and StandardSchemaValidationPipe, which Nest 12.1 supports.

create() returns the endpoint together with its secret, a Standard Webhooks whsec_… value of 32 random bytes, generated by the package. The API shows it this once: list() and get() never include it, and a partner that lost it rotates. The package stores the secret (sealed when encryption is set) because it signs with it, and getSecret() reads the current one back, for a "reveal" button behind a fresh sign-in if the API offers one. Endpoints migrated from Svix or another Standard Webhooks sender keep their secrets: pass the partner’s existing whsec_… as secret to create() or to rotateSecret().

The package refuses what a partner may not subscribe to, with an InvalidWebhookEndpointError that carries a 400 status: a URL that is not https:// (or http:// with allowHttp), that carries credentials, or whose host is a blocked address such as https://169.254.169.254/latest/meta-data/ or https://localhost/, and an event type that is not in eventTypes. A not-found endpoint or delivery of another tenant is a WebhookEndpointNotFoundError or WebhookDeliveryNotFoundError with a 404 status. All of them extend WebhooksError, and one exception filter turns them into HTTP responses:

Registered as { provide: APP_FILTER, useClass: WebhooksErrorFilter } in the module, as in Exception filters and error handling. Source: Webhooks, "Let partners subscribe".

The behaviour confirmed by the e2e test, with the responses a partner sees:

An event type outside eventTypes gets a 400 whose message lists the known types (Known: order.shipped, order.cancelled), and an endpoint of another partner gets a 404. Source: Webhooks, "Try it".

SSRF protection is not only checked at subscription time. The URL is untrusted input, and DNS can change after it was accepted, so the default transport resolves the host itself, checks every address it resolves to, pins the socket to the checked address, never follows redirects and ignores proxy settings in the environment. delivery.allowHttp and delivery.allowPrivateNetworks are off by default: only public https:// endpoints are accepted. Turn them on in development only (the official tutorial uses WEBHOOKS_ALLOW_LOCAL=1 for a receiver on the same machine). Link-local and cloud metadata addresses stay blocked even then. Use delivery.allowedAddresses (CIDR ranges such as 10.20.0.0/16) for the one private range you really deliver to, and alert on the destination-blocked event: a customer pointing a webhook at your metadata service is worth a look. For the equivalent when your own code calls arbitrary URLs, see HTTP client.

Webhooks.dispatch() takes your transaction handle first, like Outbox.add(). With Drizzle that is the tx that db.transaction() passes to its callback, and the service injects Webhooks<Transaction> so the handle is typed. tenant is the partner that owns the data, so only that partner’s endpoints receive the message:

Source: Webhooks, "Send order.shipped and order.cancelled after the commit".

Nothing leaves the process inside the transaction. If it rolls back, the message never existed (the e2e test forces a failure after dispatch() and finds the order still placed and no request recorded). If it commits, the outbox relay picks the message up (notify() asks it to do so now instead of at its next poll) and hands it to the package’s fan-out, which creates one delivery per enabled endpoint of the tenant that subscribed to the type; the worker then signs and sends each. dispatch() accepts one message or an array, with type, data, tenant and an optional id, and throws a TypeError for an unknown type, data that is not JSON-serializable or an invalid id. This is the request the partner’s server receives, on every attempt of the delivery, with the same webhook-id and the exact body that was serialized at dispatch():

Source: Webhooks, "Send order.shipped and order.cancelled after the commit". The header names, the v1, signature prefix, the msg_ id prefix and the user agent are those of the requests recorded by InMemoryWebhookTransport in the e2e test.

The type and data fields belong to your event, and the timestamp in the body is when the message was dispatched (not when this attempt was signed, which webhook-timestamp records). Because the signature follows Standard Webhooks, any Standard Webhooks library can verify it on the partner’s side, or the same package can, as the section on receiving shows.

A 2xx from the partner is a success. Anything else is a failed attempt: a 5xx, a 4xx, a 3xx (redirects are never followed), a timeout or a refused connection. The worker retries after the backoff and honors a Retry-After header in seconds or as an HTTP date, up to the backoff’s cap (any other value is ignored). On a 429, 502, 503 or 504 it also pauses that endpoint until then (five seconds without a header): the endpoint’s other deliveries wait without an attempt, so a partner asking for a breather gets one probe, not one per batch, while other partners' deliveries go on. Three answers end a delivery early: a 410 Gone, which also disables the endpoint (reason gone); a destination the transport refuses (the checks run again at every send, because DNS changes); and retry.retryIf returning false. After the last attempt, the delivery is failed with the reason exhausted.

An endpoint that fails every attempt for disableEndpointAfter is disabled with the reason failing, and WebhooksEvents emits endpoint-disabled: tell the partner. A success at any point resets the clock. A disabled endpoint, whether disabled by the worker or by the partner (enabled: false in the subscription update()), gets no delivery for anything dispatched while it stays disabled, and a replay does not bring those back, because a replay re-sends deliveries that exist. What does exist are deliveries that were pending when the endpoint was disabled: they fail with the reason endpoint-disabled, and after re-enabling, the partner can ask for those again as the failed deliveries they are.

Every attempt is logged: the status code, the duration, the first 4 KB of the response body (delivery.maxResponseSize) and the error. The partner reads its own log, and asks for one delivery or every failed one since an outage began to be sent again:

Source: Webhooks, "Retries, the delivery log and replay". In the e2e test a 503 produced a pending delivery with attempts: 1 and lastStatusCode: 503, the clock was moved past the backoff, the next worker run delivered it, the log showed attempts [503, 200], and a replay appended a third attempt with the same webhook-id.

A retry starts a new round: attempts back to 0, sent now, with the same webhook-id and the same body. The log of the earlier rounds stays. Because the id is the same, a partner whose inbox kept it answers 2xx without running its handler, so a replay is safe for a delivered webhook too: a partner can ask for the last hour again after losing its own database and get only what it has not processed. The over-HTTP test confirmed this: a replayed delivery was answered 204 and the receiver’s handler did not run again.

Operators use the same services without a tenant: WebhookDeliveries.stats() (pending, due, leased and failed counts and lagMs, how long the most overdue delivery has waited, the number to alert on), retry() across tenants, and prune('30d'), which nothing calls for you (schedule it, see Events, scheduling and queues). WebhooksEvents.events$ emits delivered, retry-scheduled, delivery-failed, endpoint-disabled, destination-blocked and verification-failed, and each is also published on a node:diagnostics_channel channel named nestjs:webhooks:<type>:

Source: Webhooks, "Reference" (Events). An e2e test that subscribes to events$ receives retry-scheduled, delivered, endpoint-disabled (after a 410) and verification-failed.

Verification needs the body exactly as the sender signed it, so create the application with rawBody: true (shown above). It works on Express and on Fastify: test the Express path through supertest and the Fastify path through app.inject(). Senders go into the module’s receivers option, by the name the route will use. Each receiver takes:

Source: Webhooks, "Reference" (Module options).

@VerifyWebhook('payments') on a route (or a controller) verifies the request before the handler runs, and @IncomingWebhook() injects what was verified: the receiver’s name, the sender’s id for the webhook, the signed timestamp, the payload parsed from the signed bytes, the rawBody, and processInTransaction(). @WebhookPayload() injects the payload alone and takes pipes like @Body(). This handler marks an order paid exactly once:

Source: Webhooks, "Receive the payment provider’s webhooks".

What the decorator checks, in order: the three webhook- headers are present and well formed (a webhook-id of at most 255 characters); one v1, signature in webhook-signature matches the HMAC of id.timestamp.body with one of the configured secrets, compared in constant time (several secrets can be listed while the provider rotates); the signed timestamp is within the tolerance (5 minutes) of now, in either direction; and the body is JSON. A request that fails gets a 401 with a generic message, and the reason never goes to the sender: it goes to the verification-failed event with the receiver’s name. A signed body that is not JSON gets a 400 from the framework’s body parser before the decorator sees it. A request whose body was not kept raw gets a 415 if it is not JSON or a form, and a 500 that logs the missing rawBody: true otherwise.

The e2e test confirmed this behaviour on Express: a valid request returned 200; a tampered body (the verifier works on the raw bytes, so one extra space is enough), a wrong secret and a timestamp one hour old each returned 401 with the body {"message":"Webhook signature verification failed","error":"Unauthorized","statusCode":401}, and the verification-failed events carried the reasons invalid-signature and timestamp-out-of-tolerance.

A secret leaks, or a partner’s policy says a year is enough. Rotating returns a new secret, and the old one keeps signing next to it for secretRotationOverlap (24 hours by default): every delivery carries two v1, signatures separated by a space, and a Standard Webhooks verifier accepts any one that matches. The partner adds the new secret to its list, deploys, and removes the old one, on its own schedule. After the overlap only the new secret signs. rotateSecret() with overlap: 0 retires the old one at once, for a leaked secret:

Source: Webhooks, "Rotate secrets". The test confirmed both: after a rotation the recorded request had two signatures and isSignedWith() accepted the old and the new secret; after overlap: 0 it had one signature and the old secret no longer matched.

Set WEBHOOKS_ENCRYPTION_KEYS (the official tutorial generates each key with openssl rand -base64 32, newest first) to seal secrets at rest through the encryption option; endpoints created before are still read and are sealed at their next rotation. Keep the keys in a secret manager. The rotation of the receiving side works the same way in reverse: list the old and the new secret in receivers.<name>.secret while the provider rotates.

The worker sends through the WebhookTransport provider. The default, HttpWebhookTransport, is built from the delivery options and does one POST per attempt over node:http and node:https. Its constructor takes two options that delivery does not: ca, certificate authorities to trust besides Node’s own (for endpoints behind a private CA), and lookup, a replacement for the system resolver (every address it returns is still checked). Pass an instance as transport, with the same allowHttp, allowPrivateNetworks and allowedAddresses as delivery; delivery still decides which URLs WebhookEndpoints accepts, and the transport decides what it connects to:

Source: Webhooks, "Reference" (Transports). The module definition (with the allow-list) was built in the test; the ca option was not exercised against a private CA.

A transport of your own extends WebhookTransport and implements send(request, options), where options carries the attempt’s signal and its attempt number; it resolves with the response’s status code, headers and the start of its body whatever the status, and throws only when there is no response. NonRetryableWebhookError and WebhookDestinationBlockedError fail the delivery without a retry. A custom transport replaces the SSRF guard with whatever it does itself, so one that sends through an egress proxy that enforces it is a reason to write one, while wrapping HttpWebhookTransport keeps the guard. InMemoryWebhookTransport is the test double described next.

In an e2e test, keep the outbox, both stores, the migrations, the fan-out, the signing and the verification real, and replace only the network. Turn the relay and the worker off with the options the module reads (OUTBOX_RELAY=off, WEBHOOKS_WORKER=off in the example), drive them by hand with relay.runOnce() and worker.runOnce(), override WebhookTransport with InMemoryWebhookTransport, and sign the providers' requests with signWebhook() from @nestjs/webhooks/testing:

Source: Webhooks, "Testing" and Testing, "End-to-end testing". See also Testing.

The official tutorial’s own tests replace the database with PGlite and run the real migrations; the e2e tests behind this page used the same idea with DrizzleModule creating the in-process database and the stores migrating their schemas at startup.

Outgoing webhooks are delivered at least once, and the receiver deduplicates by webhook-id:

Source: Webhooks, "Delivery guarantees".

Deliveries have no order. A worker sends one endpoint’s deliveries one at a time, most overdue first, but a failed attempt waits out its backoff while later messages go out, several workers send to the same endpoint at once, and a replay sends an old message now. Two updates of one order can reach the partner in either order, so a receiver ignores an event older than the state it already holds (the body’s timestamp is when the message was dispatched) or treats the webhook as a signal and reads the current state from the API. Incoming webhooks run their handler once per webhook id and receiver in the common case with the default inbox, and their processInTransaction() work exactly once. See Delivery Guarantees for the general vocabulary.

Before @nestjs/webhooks, the pattern for receiving was a guard that checks an HMAC on the raw body. It is still a valid choice for a single sender with a simple scheme and no need for a delivery log, and it is the right size when the package’s pre-1.0 status is a concern. The essentials are the same as the package’s: keep the raw body (rawBody: true), compute the HMAC over the exact bytes, compare in constant time with timingSafeEqual (compare lengths first, because it throws on different lengths), and reject old timestamps. Deduplication, retries and the delivery log are then yours to build:

Source: Raw body (the RawBodyRequest type and rawBody: true) and Guards; the HMAC check itself uses node:crypto and is not from the official docs. The test confirmed that the exact signed body passes and that a re-serialized body (the same JSON without the space) is refused, as are a wrong signature and a stale timestamp. See Guards and Custom decorators for wiring a guard and a decorator together.

Source: Webhooks, "Production checklist".

In the Bookshelf scenario used across this section, webhooks are how the application tells the outside world what it cannot reach over a WebSocket or a microservice transport: a publisher or a library partner could subscribe (tenant is the partner) to events such as book.published, and the service that publishes a book would dispatch book.published in the same transaction that sets the book’s state (see Data and TypeORM for the transactions); this scenario is illustrative and was not built. The cover-upload flow and the in-process events described in Events, scheduling and queues stay inside the application; webhooks are the same idea across a trust boundary, with signatures, retries and a log because the receiver is not yours. For one-way streaming to browsers use Server-Sent Events instead.