basalt / webhooks/src / WebhooksPluginOptions
Interface: WebhooksPluginOptions
Defined in: webhooks/src/index.ts:523
Fan-out bounds for WebhookManager.dispatch. webhooksPlugin forwards them.
Extends
Properties
allowSharedSecret?
> optional allowSharedSecret?: boolean
Defined in: webhooks/src/deliver.ts:155
Opt-out: sign tenant-bound endpoints that have no own secret with the shared default secret. Off by default — such deliveries are refused.
Inherited from
WebhookDelivererOptions.allowSharedSecret
allowUnsigned?
> optional allowUnsigned?: boolean
Defined in: webhooks/src/deliver.ts:161
Opt-out: send deliveries unsigned when neither the endpoint nor the deliverer has a secret. Off by default — unsigned deliveries are refused, since receivers could not tell them from forgeries.
Inherited from
WebhookDelivererOptions.allowUnsigned
backoffMs?
> optional backoffMs?: number
Defined in: webhooks/src/deliver.ts:165
Base backoff in ms, doubled per attempt. Default 500.
Inherited from
WebhookDelivererOptions.backoffMs
deliverer?
> optional deliverer?: WebhookDeliverer
Defined in: webhooks/src/index.ts:525
dispatchConcurrency?
> optional dispatchConcurrency?: number
Defined in: webhooks/src/index.ts:182
Most deliveries one dispatch runs at once. Default DEFAULT_DISPATCH_CONCURRENCY (16).
Inherited from
WebhookFanOutOptions.dispatchConcurrency
events?
> optional events?: string[]
Defined in: webhooks/src/index.ts:527
Domain event patterns to auto-dispatch (requires @basaltkit/events).
fetchImpl?
> optional fetchImpl?: (input, init?) => Promise<Response>
Defined in: webhooks/src/deliver.ts:182
(Advanced) custom HTTP client. The default is NOT global fetch but a built-in transport that pins the socket to the SSRF-validated IP (defeats DNS rebinding). A custom fetchImpl receives that IP on its init object under PINNED_ADDRESS but plain fetch ignores it and re-resolves the hostname, re-opening the rebind window. To keep pinning, delegate to pinnedFetch (or pin via your own dispatcher) and set fetchImplPinsAddress: true. Otherwise the deliverer warns once (BASALT_WEBHOOKS_UNPINNED_FETCH) and re-validates the host before every retry — which narrows, but cannot close, the window.
Parameters
input
string | URL | Request
init?
RequestInit
Returns
Promise<Response>
Inherited from
WebhookDelivererOptions.fetchImpl
fetchImplPinsAddress?
> optional fetchImplPinsAddress?: boolean
Defined in: webhooks/src/deliver.ts:188
Declares that the custom fetchImpl honours init[PINNED_ADDRESS] (e.g. it delegates to pinnedFetch). Silences the unpinned-fetch warning and skips the per-retry re-validation.
Inherited from
WebhookDelivererOptions.fetchImplPinsAddress
maxEndpointsPerDispatch?
> optional maxEndpointsPerDispatch?: number | false
Defined in: webhooks/src/index.ts:180
Most active endpoints ONE scope (a tenant, or the tenant-agnostic set) may have subscribed to one event. A dispatch that matches more refuses that scope entirely — none of its endpoints is sent to, each gets a failed result (retryable: false) — rather than silently picking some of them; other scopes of the same dispatch are unaffected. false disables the cap. Default DEFAULT_MAX_ENDPOINTS_PER_DISPATCH (100).
Inherited from
WebhookFanOutOptions.maxEndpointsPerDispatch
maxRetries?
> optional maxRetries?: number
Defined in: webhooks/src/deliver.ts:163
Retries after the first attempt. Default 3.
Inherited from
WebhookDelivererOptions.maxRetries
now?
> optional now?: () => number
Defined in: webhooks/src/deliver.ts:191
Clock in seconds, for deterministic tests.
Returns
number
Inherited from
onFanOutExceeded?
> optional onFanOutExceeded?: (info) => void
Defined in: webhooks/src/index.ts:187
Called once per refused scope (alerting/metrics). Default: console.warn. Must not throw — an exception is logged and swallowed.
Parameters
info
Returns
void
Inherited from
WebhookFanOutOptions.onFanOutExceeded
secret?
> optional secret?: string
Defined in: webhooks/src/deliver.ts:150
Default signing secret (an endpoint's own secret overrides it). At least MIN_WEBHOOK_SECRET_LENGTH characters. It is only used for tenant-agnostic endpoints: a tenant-bound endpoint must carry its own secret (see allowSharedSecret), since a secret shared by every tenant would let one tenant forge webhooks another tenant's receiver accepts.
Inherited from
WebhookDelivererOptions.secret
sleep?
> optional sleep?: (ms) => Promise<void>
Defined in: webhooks/src/deliver.ts:189
Parameters
ms
number
Returns
Promise<void>
Inherited from
ssrf?
> optional ssrf?: false | SsrfGuardOptions
Defined in: webhooks/src/deliver.ts:198
SSRF guard for the delivery URL. By default every delivery is refused if the URL scheme isn't http(s) or the host is/resolves to a private, loopback, link-local, CGNAT, ULA or reserved address. Set ssrf.allowPrivateHosts: true only for a trusted self-hosted setup that delivers to internal hosts.
Inherited from
store?
> optional store?: WebhookStore
Defined in: webhooks/src/index.ts:524
timeoutMs?
> optional timeoutMs?: number
Defined in: webhooks/src/deliver.ts:170
Per-attempt deadline in ms, covering DNS resolution AND the request: a resolver that hangs fails the attempt like a slow receiver does. Default 10s.