API ZeeDo

Создайте ключ в разделе «Настройки → API и вебхуки» (владелец сначала подтверждает, что это он), затем вызывайте API с ним как с bearer-токеном. Базовый URL: https://api.zeedo.cloud/v1.

curl https://api.zeedo.cloud/v1/me \
  -H "Authorization: Bearer <ваш ключ API>"

• Ключи принадлежат организации, имеют область действия — read, write или admin — и могут быть ограничены одним рабочим пространством.
• Тела в JSON, поля в snake_case, время в ISO 8601 UTC.
• Ошибки — документы проблем RFC 9457: type, title, status, detail и, для отклонённого поля, errors[] с указателем JSON.
• Списки разбиты на страницы с помощью limit (не более 200) и next_cursor.
• Отправляйте заголовок Idempotency-Key с каждым POST: повтор в течение 24 часов вернёт тот же ответ, что и первый запрос.
• 600 запросов в минуту и 10 открытых потоков на ключ, с заголовками RateLimit-*.

Организация регистрирует одну конечную точку («Настройки → API и вебхуки» или POST /webhooks) и выбирает события. Каждое событие — POST с JSON, содержащим идентификаторы, тип и метки времени, — никогда имя, адрес электронной почты или IP-адрес человека: их вы читаете через API с ключом.

{
  "id": "evt_eu_01J9ZQ3M7X5V2K8R4T6Y1N0PBA",
  "type": "run.completed",
  "version": 1,
  "occurred_at": "2026-09-27T10:02:31.000Z",
  "org_id": "org_eu_01J9ZQ1C4H8D6F2W5S7K3M9QXE",
  "data": {
    "run_id": "run_eu_01J9ZQ2V8N4B6C1X3Z5Q7W9ERT",
    "bot_id": "bot_eu_01J9ZQ2A3S5D7F9G1H3J5K7L9M"
  }
}

Каждая доставка подписана: ZeeDo-Signature: t=<секунды unix>,v1=<подпись>, где подпись — шестнадцатеричный HMAC-SHA256 от <t>.<исходное тело> с секретом вашей конечной точки. После смены секрета прежний ещё 24 часа подписывает рядом с новым, как второй v1. Отклоняйте подпись старше 5 мин.

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

// header: значение ZeeDo-Signature; body: исходное тело запроса до разбора JSON
export function verified(header, body, secret) {
  const parts = header.split(',');
  const t = parts.find((p) => p.startsWith('t='))?.slice(2);
  if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${body}`).digest('hex');
  return parts.filter((p) => p.startsWith('v1=')).some((p) =>
    p.length === expected.length + 3 && timingSafeEqual(Buffer.from(p.slice(3)), Buffer.from(expected)));
}

• Ответьте любым кодом 2xx в течение 10 секунд. Всё остальное — ошибка, перенаправление, отсутствие ответа — повторяется с растущими паузами 24 часа; затем доставка попадает в недоставленные (dead letter), хранится 7 дней, и её можно отправить снова из настроек.
• Доставка выполняется как минимум один раз и в произвольном порядке: пропускайте id, который уже обработали.
• Запросы также содержат ZeeDo-Event-Id, ZeeDo-Event-Type и ZeeDo-Delivery-Id. Конечные точки — https на порту 443 с публичным именем хоста.
• События: alert.fired, approval.decided, approval.requested, billing.service_state_changed, bot.state_changed, budget.threshold, connection.created, connection.error, consent.recorded, memory.note_created, policy.updated, run.cancelled, run.completed, run.failed, run.parked, task.completed и task.created.
• Чтобы проверить конечную точку, нажмите «Отправить тест» в разделе «Настройки → API и вебхуки»: придёт одна доставка типа webhook.test с пустым data, подписанная, как и все остальные, независимо от выбранных событий. Не чаще одного раза в минуту.