Webhooks

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
  };
}
FieldMeaning
idUnique event identifier. Identical across every retry of the same event, so use it to deduplicate.
typeWire event name, dotted lowercase. The GraphQL enum name differs - see the catalogue.
timestampWhen the event occurred, ISO-8601 UTC. Not the time of this delivery attempt.
dataPer-event payload. Shapes are on each event page; the reusable ones are in shared types.
meta.organisationIdThe client org. Route on this or on externalId.
meta.externalIdYour own client ID. Absent only if you never set one at provisioning.
meta.partnerIdYour provider org. Present on tech-provider fan-out deliveries; absent on org webhooks.
meta.apiVersionPinned to "2026-04-01". A breaking change to any data shape bumps it; adding an optional field does not.
meta.attempt1-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>
HeaderValue
X-Wexio-EventSame as envelope.type. Lets you route before parsing the body.
X-Wexio-Event-IdSame as envelope.id.
X-Wexio-AttemptSame as envelope.meta.attempt.
X-Wexio-TimestampSame as envelope.timestamp - the event time, ISO-8601.
Idempotency-KeySame as envelope.id, for HTTP middleware that expects this name.
X-Wexio-Signaturet=<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.

  1. Parse t and every v1 out of X-Wexio-Signature.
  2. Compute the HMAC over `${t}.${rawBody}` with your whsec_ secret. Use the raw request body - re-serialized JSON will not match.
  3. Accept if any v1 matches, comparing in constant time.
  4. Reject when t is more than 300 seconds off your clock.
  5. Dedupe on X-Wexio-Event-Id. Retries reuse the event id while each attempt gets a fresh t and 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 responseResult
2xxAcknowledged. No retry.
5xx, 408, 425, 429, timeout, or a network failureRetried. Up to 6 attempts, exponential backoff starting at 2 seconds.
Any other 4xxNot retried. The event is dropped.
3xx redirectNot 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.

ConsequenceWhat to do
Your mirror can store one thread several timesDeduplicate on the ids the call returned, and on the envelope id
Your delivery log grows ~4× faster than the number of conversations startedSize 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 (equivalently X-Wexio-Event-Id or Idempotency-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.created and a following chat.updated can arrive out of order. Reconcile on the timestamps in data, not on arrival order.
  • A PAUSED subscription 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 PAUSED or 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.

Was this page helpful?

On this page