Outbound Webhooks

Outbound webhooks let Wexio push data into external systems whenever something meaningful happens — a contact is created, a message is delivered, a flow reaches a checkpoint you care about. Wexio signs each delivery, retries on failure, and logs every attempt for 30 days.

Delivery Flow

Something happens in Wexio
            │
            ▼
WebhookOutboundEventsService.emit(eventName, data)
            │
            ▼
Find active OUTBOUND connections subscribed to the event
            │
            ▼
Enqueue a delivery job per connection (BullMQ, non-blocking)
            │
            ▼
Worker POSTs the signed envelope to your URL, with retries
            │
            ▼
Write WebhookDeliveryLog (PENDING → SUCCESS / FAILED / DEAD_LETTER)

Emission is fire-and-forget — Wexio never waits for the delivery to complete before continuing, and a failed POST never blocks whatever produced the event.

Creating an Outbound Connection

From Settings → Webhooks & API, tap New connection and choose Outbound.

Field	Description
Name	Display name
URL	Where Wexio should POST events
Auth type	`None`, `Bearer`, `Basic`, or `HMAC`
Subscribed events	Which events trigger a delivery to this connection

Authentication

Choose what headers Wexio attaches to every POST.

Auth type	Header	Typical use
None	—	Endpoints that don't require auth (internal, IP-allowlisted)
Bearer	`Authorization: Bearer <token>`	Most SaaS APIs, your own backend
Basic	`Authorization: Basic <base64(user:pass)>`	Legacy systems
HMAC	`X-Wexio-Signature: t=<unix>,v1=<hex>`	Receivers that want to verify the payload came from Wexio

See Envelope & Delivery for the exact headers, signing scheme, retry policy, and verification pseudo-code.

Credentials are AES-256-GCM encrypted at rest and never returned to clients.

Event Catalogue

Subscribe to any combination of these via the connection's Subscribed events picker.

Event	Reference
`chat.created`	Chat Created
`chat.updated`	Chat Updated
`chat.deleted`	Chat Deleted
`message.inbound.created`	Message Inbound Created
`message.inbound.updated`	Message Inbound Updated
`message.inbound.deleted`	Message Inbound Deleted
`message.outbound.created`	Message Outbound Created
`message.outbound.updated`	Message Outbound Updated
`message.outbound.deleted`	Message Outbound Deleted
`contact.created`	Contact Created
`contact.updated`	Contact Updated
`contact.deleted`	Contact Deleted
`flow.<suffix>` / `flow`	Flow Custom Events

Shared payload shapes (ChatPayload, ContactPayload, MessagePayload, enums) are documented once in Shared Types.

Custom `flow.*` events

Drop an Outbound Webhook Event card into any flow to emit a custom event with a payload of your choice. The card lets flow authors type a suffix like order_confirmed which Wexio delivers as flow.order_confirmed.

Subscribe to the flow namespace marker to receive every flow.* event from your organisation — one subscription covers all custom flow events, no matter what suffixes the authors invent later.

To receive only one specific custom event, subscribe by its exact name (e.g. flow.order_confirmed). To receive every flow.* event, subscribe to flow. Both are valid; pick whichever matches how your subscriber processes events.

Retries & Delivery Log

Every attempt is persisted for 30 days. The same eventId can appear across several rows — one per attempt — until delivery succeeds or is dead-lettered.

Status	Meaning
`PENDING`	Enqueued, not yet attempted
`SUCCESS`	2xx response from your endpoint
`RETRYING`	Non-2xx response or network error; Wexio will retry with exponential backoff
`FAILED`	Last retry failed — moves to DEAD_LETTER on the next cycle
`DEAD_LETTER`	Retries exhausted; no further automatic attempts

Dead-lettered events remain in the log so you can inspect the last response body and retry manually from the UI if needed.

Emit Custom Events from Flows

Add the Outbound Webhook Event card anywhere in a flow. The card:

Resolves flow variables in the event name suffix (so flow.order_{{webhook.order.id}} becomes flow.order_abc123 at runtime).
Parses a raw JSON payload (authored in a Monaco editor) with variable interpolation applied before JSON.parse.
Calls the outbound emit path — non-blocking, advances to the next card immediately.

The card is PRO+ gated. See the card reference for full config details.

Rules and Caveats

Fire-and-forget — emission never blocks flows or core operations. A broken subscriber URL has no effect on Wexio performance.
Retries use exponential backoff to your URL. Return 2xx as soon as you've accepted the payload — do the heavy work asynchronously on your side.
Idempotency is on you. The same event can arrive multiple times (retries, network partitions). Dedupe by X-Wexio-Event-Id (equivalent to meta.eventId).
Envelope data root is always an object. Arrays and primitives emitted from the custom card are wrapped under { "value": ... } for stability.
Per-connection scope. Each connection subscribes independently — deleting or pausing one does not affect the others.
No cross-org leaking. Outbound deliveries are tenant-scoped; a connection only ever receives events from the organisation that owns it.

Pause & Resume

Pausing an outbound connection stops new deliveries without deleting history. In-flight retries already enqueued will drain, but no new events are dispatched. Resume to reconnect.

Rotate the HMAC Secret

If you're using HMAC auth, rotate the signing secret from the connection detail page. Wexio generates a new secret; update your verifier to accept either the old or new value for a grace window, then switch.

Envelope & Delivery — headers, signing, retry policy
Shared Types — ChatPayload, ContactPayload, MessagePayload, enums
Webhook History — delivery logs and live-tail subscription

Outbound Webhooks

On this page