Generated from integrations/webhook/README.md by apps/docs/scripts/gen-workspace-readme-docs.js. Do not edit this page directly.

@open-wa/integration-webhook

Webhook delivery integration plugin for open-wa

Part of the @open-wa v5 monorepo.

What it does

@open-wa/integration-webhook forwards public open-wa events to an external URL with HTTP POST. It supports event filtering, custom headers, request timeouts, retry with exponential backoff, and concurrent delivery through a queue.

Use this integration when another service should receive open-wa runtime events without embedding open-wa directly.

Configuration

The plugin config is validated by the plugin SDK schema in src/plugin.ts.

Field	Required	Source-visible behavior
`url`	Yes	Target URL for webhook delivery. Must be a URL.
`events`	No	`all` or an array of event names. Defaults to `all`. Non-matching events are skipped.
`concurrency`	No	Max concurrent deliveries. Defaults to 10.
`retries`	No	Number of retry attempts after a failed delivery. Defaults to 3.
`retryDelay`	No	Base retry delay in milliseconds. Defaults to 1000 and is exponentially backed off per attempt.
`headers`	No	Additional headers merged into each request.
`timeout`	No	Request timeout in milliseconds. Defaults to 30000.

Each delivery also sends Content-Type: application/json.

Payload envelope

The payload shape is defined by WebhookPayload in src/config.ts and produced in src/plugin.ts.

Field	Value
`webhookId`	A random UUID generated when the plugin initializes.
`sessionId`	The current open-wa session ID from the plugin host.
`event`	The event name received by the plugin.
`payload`	The event payload received by the plugin.
`timestamp`	`Date.now()` at delivery enqueue time.

Runtime behavior

During initialization, the plugin creates a WebhookDeliverer, computes the allowed event set, and logs the configured target URL.
On each public event hook call, the plugin skips events outside the configured allowlist and enqueues the payload for delivery.
WebhookDeliverer posts JSON with native fetch and aborts requests with AbortController when the timeout elapses.
Non-2xx responses throw an error and enter the retry path.
Retry delay is retryDelay * 2 ** attempt until the configured retry count is exhausted.
Failed deliveries are logged after all attempts; the error is not rethrown from the final retry path.
On dispose, the plugin waits for the queue to become idle and logs that the queue drained.

Exports

Default export and webhookPlugin from src/plugin.ts.
WebhookDeliverer from src/deliverer.ts.
WebhookPluginConfig, WebhookConfig, Webhook, and WebhookPayload types.

Development

pnpm --filter @open-wa/integration-webhook build
pnpm --filter @open-wa/integration-webhook dev
pnpm --filter @open-wa/integration-webhook lint
pnpm --filter @open-wa/integration-webhook clean

Documentation

See the docs site.

License

H-DNH V1.0 - Hippocratic + Do Not Harm

Was this helpful?

Wally and his cute companion coffee mug are coding day and night to keep this up-to-date!

Was this helpful?

On this page