Webhooks reference — Helio Docs

Subscribe to Helio events — message sent, cart recovered, agent handoff — and receive signed payloads at your own endpoint.

Overview

Webhooks let your systems react to what Helio does in real time. Register an endpoint, subscribe to one or more event types, and Helio will POST a signed JSON payload every time a matching event occurs.

Webhooks are in beta. Event names and payload fields may change before general availability — pin to the version field in each payload.

Events

Every payload carries a type from the table below.

Event	Fires when	Stability
`message.sent`	The agent sends a message on any channel	Stable
`message.received`	A customer replies	Stable
`cart.recovered`	An abandoned cart converts after an agent touch	Stable
`agent.handoff`	A conversation is escalated to a human	Beta
`campaign.completed`	An A/B test reaches statistical significance	Beta

Payload shape

All events share an envelope; the data object varies by type.

JSON Copy

{
  "id": "evt_2a9f...",
  "type": "cart.recovered",
  "version": "2026-05-01",
  "created_at": "2026-05-20T11:04:22Z",
  "data": {
    "cart_id": "c_88c1",
    "customer_id": "cus_41d0",
    "channel": "whatsapp",
    "recovered_value": 128.40,
    "currency": "USD"
  }
}

Verifying signatures

Each request includes an X-Helio-Signature header — an HMAC-SHA256 of the raw body using your endpoint's signing secret. Always verify it before trusting a payload.

JavaScript Copy

import crypto from "node:crypto";

function verify(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Delivery & retries

Behavior	Value
Expected response	`2xx` within 5 seconds
Retry schedule	6 attempts over 24h (exponential backoff)
Timeout	5s per attempt
Ordering	Best-effort; use `created_at`, not arrival order

Endpoints that fail every retry for 7 consecutive days are automatically disabled. You'll get an email before that happens.

Next steps

Core concepts — the Agents / Channels / Playbooks model your events come from
Install on Shopify to start generating events