Webhooks

How it works

1. You register an endpoint URL on your server and choose which events to receive.
2. When a matching event happens in Zoye, we POST a signed JSON payload to that URL.
3. Your server verifies the signature, does its work, and responds with a 2xx status to acknowledge.
4. If your server is down or returns a non-2xx, we retry with exponential backoff.

Set it up

Webhooks are managed in the app, not with an API key. Open the Sync Users & Subscribers connector, choose Send updates out, then:

1. Add the endpoint URL on your server that should receive events.
2. Pick the events you care about (or all of them).
3. Copy the signing secret (whsec_...) shown once on creation, and store it on your server. You use it to verify every delivery.

Events

Payload

Every delivery is a JSON object with the event name, an ISO 8601 timestamp, the workspace id, and a data object with the contact. The data shape matches the contact you get back from the REST API.

{
  "event": "contact.created",
  "timestamp": "2026-06-05T12:34:56.000Z",
  "workspace_id": 1624,
  "data": {
    "id": 1054,
    "email": "jordan@northwind.com",
    "name": "Jordan Rivera",
    "phone": "+15551234567",
    "company": "Northwind",
    "position": "CTO",
    "tags": ["vip"],
    "source": "website-form",
    "lifecycleStage": "Subscriber",
    "archivedAt": null,
    "externalId": null,
    "createdAt": "2026-06-05T12:34:56.000Z",
    "updatedAt": "2026-06-05T12:34:56.000Z"
  }
}

For contact.stage_changed, the data object also includes previousStage so you can see where the contact moved from:

"data": {
  "id": 1054,
  "name": "Jordan Rivera",
  "lifecycleStage": "Customer",
  "previousStage": "Lead"
  // ...the rest of the contact fields
}

Request headers

Verify the signature

Always verify the signature before trusting a payload. Compute the HMAC-SHA256 of the raw request body with your endpoint secret, prefix it with sha256=, and compare it to the X-Zoye-Signature header using a constant-time comparison. Use the raw bytes of the body, not a re-serialized object.

const crypto = require("crypto");
const express = require("express");
const app = express();

const SECRET = process.env.ZOYE_WEBHOOK_SECRET; // whsec_...

app.post(
  "/zoye-webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const signature = req.header("X-Zoye-Signature") || "";
    const expected =
      "sha256=" +
      crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");

    const a = Buffer.from(signature);
    const b = Buffer.from(expected);
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      return res.status(401).send("bad signature");
    }

    const payload = JSON.parse(req.body.toString("utf8"));
    // ...handle payload.event + payload.data...
    res.sendStatus(200);
  }
);

Retries and delivery

Respond with any 2xx status to acknowledge a delivery. Anything else (or a timeout - we wait up to 15 seconds per attempt) is treated as a failure and retried up to 5 times with exponential backoff:

You can also open any endpoint in the app to view its recent deliveries (with response status) and manually replay any that failed.

Best practices

• Verify every signature before acting on a payload, and reject anything that does not match.
• Respond fast. Acknowledge with 2xx right away and do slow work (emails, syncs) in a background job, so you never hit the 15-second timeout.
• Be idempotent. A delivery can arrive more than once on retries. Use X-Zoye-Delivery (or the contact id plus event) to skip duplicates.
• Tolerate new fields. We may add fields to data over time. Ignore unknown fields rather than failing.