Documentation

Documentation / zerotal / index / WebhookMiddleware

Class: WebhookMiddleware

Defined in: packages/core/src/middleware/WebhookMiddleware.ts:65

Verifies HMAC webhook signatures before allowing the request to proceed.

Responds with 401 Unauthorized when the signature is missing, expired, or invalid. The raw body is read once and the parsed JSON is seeded into the body cache so downstream controllers can still call await ctx.body() normally.

Example

// Generic
app.use([WebhookMiddleware.with({ secret: env('WEBHOOK_SECRET') })]);

// GitHub
Router.post('/webhooks/github', GithubController, 'handle', [
  WebhookMiddleware.github(env('GITHUB_WEBHOOK_SECRET')),
]);

// Stripe
Router.post('/webhooks/stripe', StripeController, 'handle', [
  WebhookMiddleware.stripe(env('STRIPE_WEBHOOK_SECRET')),
]);

Extends

• BaseMiddleware<WebhookOptions>

Constructors

Constructor

new WebhookMiddleware(options?): WebhookMiddleware

Defined in: packages/core/src/middleware/WebhookMiddleware.ts:75

Parameters

options?

Partial<WebhookOptions> = {}

Returns

WebhookMiddleware

Overrides

BaseMiddleware.constructor

Properties

options

protected options: WebhookOptions

Defined in: packages/core/src/middleware/WebhookMiddleware.ts:66

Subclasses must declare this with their default option values. TypeScript enforces this at compile time — forgetting it is a type error.

Overrides

BaseMiddleware.options

Methods

with()

static with<T, Opts>(this, options): () => InstanceType<T>

Defined in: packages/core/src/middleware/BaseMiddleware.ts:48

Returns a zero-arg subclass with the given options deep-merged on top of the subclass defaults, usable directly in app.use([...]).

Type Parameters

T

T extends (...args) => BaseMiddleware<any>

Opts

Opts = T extends (...args) => BaseMiddleware<U> ? U : object

Parameters

this

T

options

Partial<Opts>

Returns

() => InstanceType<T>

Inherited from

BaseMiddleware.with

afterResponse()?

optional afterResponse(ctx): Promise<void>

Defined in: packages/core/src/middleware/BaseMiddleware.ts:70

Parameters

ctx

HttpContext

Returns

Promise<void>

Inherited from

BaseMiddleware.afterResponse

onError()?

optional onError(ctx, error): Promise<void>

Defined in: packages/core/src/middleware/BaseMiddleware.ts:71

Parameters

ctx

HttpContext

error

Error

Returns

Promise<void>

Inherited from

BaseMiddleware.onError

handle()

handle(http, next): Promise<void | Response>

Defined in: packages/core/src/middleware/WebhookMiddleware.ts:80

Parameters

http

HttpContext

next

NextFn

Returns

Promise<void | Response>

Overrides

BaseMiddleware.handle

github()

static github(secret): WebhookMiddleware

Defined in: packages/core/src/middleware/WebhookMiddleware.ts:149

GitHub webhook preset: X-Hub-Signature-256 header, sha256= prefix.

Parameters

secret

string

Returns

WebhookMiddleware

stripe()

static stripe(secret, toleranceSeconds?): WebhookMiddleware

Defined in: packages/core/src/middleware/WebhookMiddleware.ts:162

Stripe webhook preset: Stripe-Signature header with t=<ts>,v1=<sig> format, 5-minute replay-attack tolerance.

Parameters

secret

string

toleranceSeconds?

number = 300

Returns

WebhookMiddleware