Contents

Guide

Webhooks

Events we send to your server, how they're signed, and retries.

Add a webhook in the account's settings with an HTTPS address and the events you want. Each event is sent as a POST with a JSON body:

{
  "id": "4821",
  "type": "tag.added",
  "created_at": "2026-11-12T17:02:11.000Z",
  "page_id": 1000001,
  "data": { "object_type": "tag", "object_id": "12", "subscriber_id": "905", "subscriber": { ... } }
}

Headers

  • X-Engage-Signature: t=<unix seconds>,v1=<hex>: an HMAC-SHA256 of <t>.<body> with the webhook's secret.
  • X-Engage-Event: the event type. X-Engage-Delivery: the delivery id, the same on every retry.

Checking the signature

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, rawBody, header) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const want = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  return timingSafeEqual(Buffer.from(want), Buffer.from(parts.v1 ?? ""));
}

Retries

Answer with any 2xx within the timeout. Otherwise we retry after 1 minute, 5 minutes, 30 minutes and 2 hours. If ten deliveries in a row fail, the webhook is switched off and the account is told why. We only send to public HTTPS addresses and don't follow redirects.

Events

  • contact.created
  • contact.updated
  • contact.deleted
  • contact.subscribed
  • contact.unsubscribed
  • contact.merged
  • tag.added
  • tag.removed
  • field.changed
  • sequence.subscribed
  • sequence.unsubscribed
  • message.received
  • message.sent
  • message.refused
  • message.failed
  • flow.started
  • flow.completed
  • growth_tool.optin
  • conversion.logged
  • conversation.opened
  • conversation.closed
  • conversation.assigned
  • order.paid
  • order.refunded
  • order.failed

Next: Dynamic content (v2 format)