Envelope & Delivery
The JSON envelope, HTTP headers, HMAC signature, retry policy, and deduplication
Every partner event - regardless of type - arrives as one POST with the same envelope, the same headers, and the same retry semantics. This page is the whole contract.
Envelope
interface PartnerWebhookEnvelope<TData> {
id: string; // "evt_<uuid>" - stable across retries; your dedupe key
type: string; // wire event name, e.g. "message.inbound.created"
timestamp: string; // ISO-8601 UTC - when the event occurred
data: TData; // per-event payload - see each event page
meta: {
eventId: string; // same value as `id`
event: string; // same value as `type`
occurredAt: string; // same value as `timestamp`
organisationId: string; // the CLIENT org the event came from
externalId?: string; // YOUR id for that client, from createClientOrg
partnerId?: string; // your provider (tech-provider) org id
apiVersion: "2026-04-01";
attempt: number; // 1-indexed delivery attempt
};
}| Field | Meaning |
|---|---|
id | Unique event identifier. Identical across every retry of the same event, so use it to deduplicate. |
type | Wire event name, dotted lowercase. The GraphQL enum name differs - see the catalogue. |
timestamp | When the event occurred, ISO-8601 UTC. Not the time of this delivery attempt. |
data | Per-event payload. Shapes are on each event page; the reusable ones are in shared types. |
meta.organisationId | The client org. Route on this or on externalId. |
meta.externalId | Your own client ID. Absent only if you never set one at provisioning. |
meta.partnerId | Your provider org. Present on tech-provider fan-out deliveries; absent on org webhooks. |
meta.apiVersion | Pinned to "2026-04-01". A breaking change to any data shape bumps it; adding an optional field does not. |
meta.attempt | 1-indexed retry counter. The same (id, attempt) pair is never posted twice. |
meta.connectionId is absent on partner deliveries - there is no per-org connection behind them. It is present on org webhooks.
HTTP Request
POST https://api.crmco.com/wexio/webhook
Content-Type: application/json
X-Wexio-Event: message.inbound.created
X-Wexio-Event-Id: evt_1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809
X-Wexio-Attempt: 1
X-Wexio-Timestamp: 2026-09-30T18:00:00.000Z
Idempotency-Key: evt_1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809
X-Wexio-Signature: t=1759255200,v1=8a3f...
<envelope JSON>| Header | Value |
|---|---|
X-Wexio-Event | Same as envelope.type. Lets you route before parsing the body. |
X-Wexio-Event-Id | Same as envelope.id. |
X-Wexio-Attempt | Same as envelope.meta.attempt. |
X-Wexio-Timestamp | Same as envelope.timestamp - the event time, ISO-8601. |
Idempotency-Key | Same as envelope.id, for HTTP middleware that expects this name. |
X-Wexio-Signature | t=<unix seconds>,v1=<hex>. See below. |
X-Wexio-Timestamp (ISO-8601, event time) and the t in X-Wexio-Signature (unix seconds, delivery time) are different values in different units. Sign with t; never substitute the header.
Verify the Signature
v1 is HMAC-SHA256(signingSecret, t + "." + rawRequestBody), hex-encoded, where t is the unix-seconds value from the same header.
Collect every v1, not just one. The header can carry more than one v1 value, and a delivery is authentic if any of them matches. A secret rotation is when a second one appears: for 24 hours after you rotate, deliveries are signed with both the new and the previous secret, unless you revoked the old one at once.
Parsing the header into a map keyed by name keeps only the last value. That looks correct while there is one value and silently rejects authentic deliveries the moment there are two, so write the parser to collect them all now rather than when it breaks.
- Parse
tand everyv1out ofX-Wexio-Signature. - Compute the HMAC over
`${t}.${rawBody}`with yourwhsec_secret. Use the raw request body - re-serialized JSON will not match. - Accept if any
v1matches, comparing in constant time. - Reject when
tis more than 300 seconds off your clock. - Dedupe on
X-Wexio-Event-Id. Retries reuse the event id while each attempt gets a freshtand signature, so the signature alone does not tell you whether you have seen this event.
The snippet below behaves correctly whether the header carries one v1 or several, so there is nothing to change later.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyWexioSignature(
rawBody: string,
header: string,
secret: string,
): boolean {
const parts = header.split(",").map((p) => p.trim());
const t = parts.find((p) => p.startsWith("t="))?.slice(2);
// Every v1, not just one: there are two during a rotation grace window.
const v1s = parts.filter((p) => p.startsWith("v1=")).map((p) => p.slice(3));
if (!t || v1s.length === 0) return false;
// t is the DELIVERY time in unix seconds.
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = Buffer.from(
createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex"),
);
return v1s.some((v1) => {
const got = Buffer.from(v1);
return got.length === expected.length && timingSafeEqual(got, expected);
});
}A verified signature means the body is authentic, not that the event is new. Keep event ids in a store with a TTL longer than the retry schedule and drop anything you have already processed.
In Express, get the raw body with express.raw({ type: "application/json" }) on the webhook route, or express.json({ verify: (req, _res, buf) => { req.rawBody = buf } }). JSON.stringify(req.body) will fail verification.
The secret comes from registerPartnerWebhook and is shown once. Rotate with rotatePartnerWebhookSecret.
Responding
| Your response | Result |
|---|---|
2xx | Acknowledged. No retry. |
5xx, 408, 425, 429, timeout, or a network failure | Retried. Up to 6 attempts, exponential backoff starting at 2 seconds. |
Any other 4xx | Not retried. The event is dropped. |
3xx redirect | Not followed and not retried. Register the final URL. |
Wexio waits 5 seconds for a response. Answer 2xx as soon as you have durably accepted the event, then process asynchronously. A slow handler burns your retry budget.
If a retried response carries a Retry-After header, Wexio waits at least that long, capped at 5 minutes. An event still undelivered 24 hours after it occurred is not sent again, and its delivery history row shows it as expired.
A 400, 401 or 404 is treated as a permanent rejection, so a bug that returns one on a valid payload silently drops events with no retry. Return 5xx for anything you might recover from.
One Action, Several Deliveries
A single API call can produce several events. The clearest case is a cold start: one trigger_conversation emits four deliveries - contact.created, conversation.created, chat.created and message.outbound.created.
| Consequence | What to do |
|---|---|
| Your mirror can store one thread several times | Deduplicate on the ids the call returned, and on the envelope id |
| Your delivery log grows ~4× faster than the number of conversations started | Size endpoint throughput and log retention on deliveries, not on conversations |
Ordinary traffic behaves the same way at smaller scale: one inbound message can produce a message.inbound.created, a chat.updated and a conversation.updated. Subscribe to the narrowest level that answers your question.
Deduplication and Ordering
- Deduplicate on
id(equivalentlyX-Wexio-Event-IdorIdempotency-Key). Events can arrive more than once - retries after a timeout where your side actually succeeded are the common case. - Do not assume ordering. Deliveries are queued per event, so
message.inbound.createdand a followingchat.updatedcan arrive out of order. Reconcile on the timestamps indata, not on arrival order. - A
PAUSEDsubscription drops matching events rather than queueing them. They are not replayed on resume.
Delivery Attempts You Will Never See
An event is not delivered at all when:
- the subscription is
PAUSEDor deleted, - the event is not in
subscribedEvents, - the client org is not one of your managed clients.
None of these produce an error on your side - the event never arrives.