A API da ZeeDo

Crie uma chave em Configurações → API e webhooks (um proprietário confirma a identidade antes) e chame a API com ela como bearer token. A URL base é https://api.zeedo.cloud/v1.

curl https://api.zeedo.cloud/v1/me \
  -H "Authorization: Bearer <sua chave de API>"

• As chaves pertencem à organização, têm um escopo — read, write ou admin — e podem ficar restritas a um espaço de trabalho.
• Corpos em JSON, campos em snake_case, horários em ISO 8601 UTC.
• Os erros são documentos de problema RFC 9457: type, title, status, detail e, para um campo recusado, errors[] com um ponteiro JSON.
• As listas são paginadas com limit (no máximo 200) e next_cursor.
• Envie um cabeçalho Idempotency-Key em todo POST: uma repetição em até 24 horas recebe a mesma resposta da primeira.
• 600 requisições por minuto e 10 streams abertos por chave, com os cabeçalhos RateLimit-*.

Uma organização registra um endpoint (Configurações → API e webhooks, ou POST /webhooks) e escolhe os eventos. Cada evento é um POST de JSON com ids, o tipo e os carimbos de data e hora — nunca o nome, o e-mail ou o endereço IP de uma pessoa, que você lê depois pela API com uma chave.

{
  "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"
  }
}

Toda entrega é assinada: ZeeDo-Signature: t=<segundos unix>,v1=<assinatura>, em que a assinatura é o HMAC-SHA256 em hexadecimal de <t>.<corpo bruto> com o segredo do seu endpoint como chave. Depois que você troca o segredo, o anterior continua assinando junto por 24 horas, como um segundo v1. Recuse uma assinatura com mais de 5 minutos.

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

// header: o valor de ZeeDo-Signature; body: o corpo bruto da requisição, antes de qualquer leitura do 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)));
}

• Responda com qualquer 2xx em até 10 segundos. Qualquer outra coisa — um erro, um redirecionamento, nenhuma resposta — é tentada de novo com intervalos crescentes por 24 horas; depois a entrega vira uma mensagem morta, guardada por 7 dias e reenviada em Configurações.
• As entregas acontecem pelo menos uma vez e sem ordem definida: ignore um id que você já tratou.
• As requisições também levam ZeeDo-Event-Id, ZeeDo-Event-Type e ZeeDo-Delivery-Id. Os endpoints usam https na porta 443, em um nome de host público.
• Eventos: 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 e task.created.
• Para verificar seu endpoint, clique em Enviar um teste em Configurações → API e webhooks: uma entrega do tipo webhook.test com data vazio, assinada como as demais e enviada quaisquer que sejam os eventos escolhidos. No máximo uma por minuto.