API reference

webhooks declares inbound receivers, outbound senders, signature policies, retries, dedupe, replay, and webhook event records.

Import

import { webhooks } from "@layeron/modules"

`webhooks.stripe`

Declare a Stripe inbound webhook receiver.

TypeSpec operation: webhooksStripe.

webhooks.stripe(options?: WebhookProviderOptions): WebhooksModule

WebhookSecretRef

Reference to a Layeron secret used for signing.

Field	Type	Description
`name`	`string`	Secret name.
`namespace`	`string \| undefined`	Platform namespace for the instance. Defaults to `default`.

WebhookSignatureConfig

Signature verification or signing settings.

Field	Type	Description
`header`	`string \| undefined`	Header containing the signature.
`headers`	`string[] \| undefined`	Headers that may contain signatures.
`queryParam`	`string \| undefined`	Query parameter containing the signature.
`extract`	`unknown \| undefined`	Signature extractor. TypeScript accepts a RegExp or a function `(ctx) => string \| Promise<string>`. The generated contract represents RegExp and function values as `unknown` because they remain application code values.
`algorithm`	`WebhookSignatureAlgorithm \| undefined`	Signature algorithm.
`encoding`	`WebhookSignatureEncoding \| undefined`	Signature encoding.
`secret`	`WebhookSecretRef \| undefined`	Secret used to verify or sign the payload.
`timestampHeader`	`string \| undefined`	Header containing the timestamp.
`timestampQueryParam`	`string \| undefined`	Query parameter containing the timestamp.
`toleranceSeconds`	`int32 \| undefined`	Allowed timestamp skew in seconds.
`signedPayload`	`WebhookSignedPayloadPreset \| undefined`	Preset used to build the signed payload.
`verify`	`unknown \| undefined`	Custom verifier. TypeScript accepts a function `(ctx) => boolean \| Promise<boolean>` that receives the request, raw body, headers, method, path, timestamp, extracted signature, and secret value. The generated contract represents the function value as `unknown`.

WebhookRetryOptions

Retry policy for webhook delivery.

Field	Type	Description
`attempts`	`int32 \| undefined`	Maximum delivery attempts.
`backoff`	`”fixed” \| “exponential” \| undefined`	Retry backoff mode.
`initialDelaySeconds`	`int32 \| undefined`	First retry delay in seconds.
`maxDelaySeconds`	`int32 \| undefined`	Maximum retry delay in seconds.

WebhookDedupeOptions

Duplicate detection settings.

Field	Type	Description
`key`	`string \| undefined`	Payload field or expression used as the idempotency key.
`ttl`	`string \| undefined`	Duplicate retention duration.

WebhookDeliveryOptions

Delivery settings for inbound webhook handlers.

Field	Type	Description
`queue`	`boolean \| undefined`	Whether delivery should be queued.
`retry`	`WebhookRetryOptions \| undefined`	Retry policy.
`deadLetter`	`boolean \| undefined`	Whether exhausted events should move to dead letter state.

WebhookProviderOptions

Options shared by inbound provider helpers.

Field	Type	Description
`name`	`string \| undefined`	Stable webhook instance name.
`namespace`	`string \| undefined`	Platform namespace for the instance. Defaults to `default`.
`path`	`string \| undefined`	Gateway path used for inbound delivery.
`host`	`string \| undefined`	Dedicated host used for inbound delivery.
`url`	`string \| undefined`	Absolute URL used to infer host or path placement.
`secret`	`WebhookSecretRef \| undefined`	Secret used for provider signatures.
`dedupe`	`WebhookDedupeOptions \| undefined`	Duplicate detection settings.
`delivery`	`WebhookDeliveryOptions \| undefined`	Delivery settings.
`on`	`Record<unknown> \| undefined`	Event-specific handler map. TypeScript accepts `Record<string, WebhookEventHandler>` keyed by provider event type. The generated contract represents handler functions as `unknown` values because they remain application code values.
`handler`	`unknown \| undefined`	Single inbound handler. TypeScript accepts a `WebhookEventHandler` function. The generated contract represents the function value as `unknown` because it remains application code.
`observability`	`Layeron.Observability.ObservabilityConfig \| undefined`	Observability settings for webhook events, attempts, and replay.

WebhookCustomOptions

Options accepted by webhooks.custom().

Field	Type	Description
`name`	`string`	Stable webhook instance name.
`signature`	`WebhookSignatureConfig \| undefined`	Custom signature verification settings.

WebhookOutboundEndpointOptions

Outbound endpoint settings.

Field	Type	Description
`name`	`string`	Stable endpoint name.
`url`	`string`	Destination URL.
`signing`	`WebhookSignatureConfig \| undefined`	Signing settings for outbound delivery.
`retry`	`WebhookRetryOptions \| undefined`	Retry policy.

WebhookManagedSecretOptions

Managed per-user outbound secret settings.

Field	Type	Description
`enabled`	`boolean \| undefined`	Whether managed secrets are enabled.
`prefix`	`string \| undefined`	Secret name prefix.
`bytes`	`int32 \| undefined`	Generated secret byte count.

WebhookOutboundOptions

Options accepted by webhooks.out().

Field	Type	Description
`name`	`string`	Stable outbound webhook instance name.
`namespace`	`string \| undefined`	Platform namespace for the instance. Defaults to `default`.
`endpoints`	`WebhookOutboundEndpointOptions[]`	Destination endpoints.
`managedSecrets`	`WebhookManagedSecretOptions \| undefined`	Managed per-user outbound secret settings.
`observability`	`Layeron.Observability.ObservabilityConfig \| undefined`	Observability settings for sends and delivery attempts.

WebhookEvent

Webhook event record.

Field	Type	Description
`id`	`string`	Layeron event id.
`direction`	`WebhookDirection`	Webhook direction.
`namespace`	`string`	Platform namespace for the instance. Defaults to `default`.
`name`	`string`	Webhook instance name.
`provider`	`string`	Provider name.
`eventType`	`string`	Provider event type.
`externalEventId`	`string \| undefined`	External provider event id.
`status`	`WebhookEventStatus`	Processing status.
`receivedAt`	`string`	Receive timestamp.
`processedAt`	`string \| undefined`	Processing timestamp.
`payload`	`unknown`	JSON payload.
`headers`	`Record<string>`	Captured request headers.

WebhookHandleResult

Result returned after handling an inbound webhook.

Field	Type	Description
`status`	`WebhookEventStatus`	Final or queued event status.
`eventId`	`string \| undefined`	Layeron event id.
`deduped`	`boolean \| undefined`	Whether a duplicate event was detected.

WebhookSendResult

Result returned after sending an outbound webhook.

Field	Type	Description
`eventId`	`string`	Layeron event id.
`deliveries`	`unknown[]`	Endpoint delivery summaries.

WebhookListEventsInput

Event list filters.

Field	Type	Description
`status`	`WebhookEventStatus \| undefined`	Status filter.
`direction`	`WebhookDirection \| undefined`	Direction filter.
`limit`	`int32 \| undefined`	Maximum events to return.

WebhookListEventsResult

Event list result.

Field	Type	Description
`events`	`WebhookEvent[]`	Matching events.

WebhooksModule

Layeron webhooks module returned by webhook helpers.

Field	Type	Description
`name`	`”webhooks”`	Module name.
`config`	`unknown`	Normalized module configuration.
`observability`	`Layeron.Observability.ObservabilityConfig \| undefined`	Effective observability policy recorded on the module declaration.

WebhookSignatureAlgorithm

Signature algorithm used for verification or signing.

Value	Description
`hmac-sha256`	HMAC signature using SHA-256.
`hmac-sha1`	HMAC signature using SHA-1 for legacy providers.
`hmac-sha512`	HMAC signature using SHA-512.
`none`	Skip signature verification or signing.

WebhookSignatureEncoding

Signature encoding used in headers or query parameters.

Value	Description
`hex`	Hex-encoded signature bytes.
`base64`	Base64-encoded signature bytes.
`base64url`	Base64url-encoded signature bytes.

WebhookSignedPayloadPreset

Preset used to build the signed payload.

Value	Description
`rawBody`	Sign the raw request body.
`timestamp.rawBody`	Sign the timestamp, a dot separator, and the raw request body.
`method.path.rawBody`	Sign the HTTP method, path, and raw request body with dot separators.

WebhookDirection

Webhook direction.

Value	Description
`inbound`	Inbound webhook receiver.
`outbound`	Outbound webhook sender.

WebhookEventStatus

Webhook event processing status.

Value	Description
`accepted`	The webhook event was accepted by the ingress path.
`duplicate`	The webhook event matched an existing dedupe key.
`signature_failed`	Signature verification failed.
`queued`	The webhook event was queued for handler execution.
`processing`	The webhook handler is running.
`processed`	The webhook handler finished successfully.
`failed`	The webhook handler or delivery attempt failed.

WebhookPlacementMode

Webhook placement mode.

Value	Description
`path`	Expose the webhook under the app gateway path.
`host`	Expose the webhook on a dedicated host.

Operations

`webhooks.github`

Declare a GitHub inbound webhook receiver.

TypeSpec operation: webhooksGithub.

webhooks.github(options?: WebhookProviderOptions): WebhooksModule

`webhooks.custom`

Declare a custom inbound webhook receiver.

TypeSpec operation: webhooksCustom.

webhooks.custom(options: WebhookCustomOptions): WebhooksModule

`webhooks.out`

Declare an outbound webhook sender.

TypeSpec operation: webhooksOutbound.

webhooks.out(options: WebhookOutboundOptions): WebhooksModule

`webhooksHandle`

Handle one inbound webhook request.

webhooksHandle(request: unknown): WebhookHandleResult

`webhooksSend`

Send one outbound webhook event.

webhooksSend(eventType: string, payload: unknown): WebhookSendResult

`webhooksListEvents`

List webhook events.

webhooksListEvents(input?: WebhookListEventsInput): WebhookListEventsResult

`webhooksReplay`

Replay one webhook event.

webhooksReplay(eventId: string): WebhookHandleResult