Get events from ioZen with webhooks

If you check bots under “Intake bots”, the endpoint only gets events that come from those bots. That way a clinic can send appointments to one system and price questions to another.

Two cases are worth knowing. A contact someone on your team creates by hand doesn't come from any bot, so it reaches every endpoint subscribed to “Contact Created”. And a case that didn't start in a bot only reaches endpoints with no bots checked.

Each event arrives as a POST with this JSON body:

{
  "id": "evt_8f2c41d07a9b4e3f9a6d1c5b7e0f2a34",
  "type": "submission.completed",
  "api_version": "2026-08-27",
  "created_at": "2026-11-06T15:04:05.000Z",
  "data": {}
}

data holds what happened and depends on the event. The full reference shows each one.

These headers come with the body:

ioZen signs every call with your secret. The signature is the HMAC-SHA256 of the text timestamp.body: the X-IoZen-Timestamp value, a dot, and the body exactly as it arrived. The key is the whole secret, whsec_ included.

Compute it from the raw body, before you parse the JSON. If you parse it and write it back out, the signature won't match. In Node.js:

import { createHmac, timingSafeEqual } from 'node:crypto'

// rawBody: the body exactly as received (text). secret: your whsec_...
export function verifyIozenWebhook(rawBody, headers, secret) {
  const timestamp = headers['x-iozen-timestamp']
  const signature = headers['x-iozen-signature'] ?? ''
  const expected =
    'sha256=' + createHmac('sha256', secret).update(`${timestamp}.${rawBody}`, 'utf8').digest('hex')

  const a = Buffer.from(expected)
  const b = Buffer.from(signature)
  if (a.length !== b.length || !timingSafeEqual(a, b)) return false

  // Reject stale calls (here, older than 5 minutes)
  return Math.abs(Date.now() / 1000 - Number(timestamp)) < 300
}

Every attempt is signed again with the current time, so retries pass this check.

Your server has 10 seconds to answer with a 2xx status. Any other response, a redirect, or no answer in time counts as a failure.

If it fails, we retry up to 5 times. A retry carries the same id, so use it to avoid handling the same event twice.

After 10 failed attempts in a row, we pause the endpoint and email the workspace owners and admins. A “Paused” endpoint gets no events. Once your server is back, tap “Resume”.

In the endpoint's menu, “Deliveries” lists recent attempts with their status, HTTP code and how long they took. “Redeliver” sends that event again right away, built from the current data and with a new id; the row is marked “Manual”.

In the endpoint's menu, “Edit” changes the events, the description and the bots. The URL can't change: create another endpoint with the new one. “Delete” removes it and stops sending it events.

The webhooks reference, with what data holds for each event, is at app.iozen.ai/docs/webhooks. To create and manage endpoints from your own code, use the ioZen API with the “Manage Webhooks” scope.