La API de ZeeDo

Cree una clave en Configuración → API y webhooks (la persona propietaria confirma antes su identidad) y llame a la API con ella como token Bearer. La URL base es https://api.zeedo.cloud/v1.

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

• Las claves pertenecen a la organización, tienen un alcance (read, write o admin) y pueden limitarse a un espacio de trabajo.
• Cuerpos JSON, campos en snake_case, horas en ISO 8601 UTC.
• Los errores son documentos de problema RFC 9457: type, title, status, detail y, para un campo rechazado, errors[] con un puntero JSON.
• Las listas se paginan con limit (200 como máximo) y next_cursor.
• Envíe una cabecera Idempotency-Key con cada POST: una repetición en 24 horas devuelve la misma respuesta que la primera.
• 600 solicitudes por minuto y 10 flujos abiertos por clave, con cabeceras RateLimit-*.

Una organización registra un endpoint (Configuración → API y webhooks, o POST /webhooks) y elige sus eventos. Cada evento es un POST de JSON con identificadores, el tipo y marcas de tiempo; nunca el nombre, el correo ni la dirección IP de una persona, que usted consulta a través de la API con una clave.

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

Cada envío va firmado: ZeeDo-Signature: t=<segundos unix>,v1=<firma>, donde la firma es el HMAC-SHA256 en hexadecimal de <t>.<cuerpo sin procesar> con el secreto de su endpoint como clave. Después de rotar el secreto, el anterior sigue firmando junto a él durante 24 horas, como un segundo v1. Rechace una firma con más de 5 minutos de antigüedad.

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

// header: el valor de ZeeDo-Signature; body: el cuerpo de la solicitud sin procesar, antes de interpretar el 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 con cualquier 2xx en 10 segundos. Cualquier otra cosa (un error, una redirección, ninguna respuesta) se reintenta con esperas crecientes durante 24 horas; después el envío pasa a mensajes fallidos (dead letter), se guarda 7 días y puede reenviarse desde Configuración.
• Los envíos llegan al menos una vez y sin un orden concreto: omita un id que ya haya procesado.
• Las solicitudes también llevan ZeeDo-Event-Id, ZeeDo-Event-Type y ZeeDo-Delivery-Id. Los endpoints usan https en el puerto 443 con un nombre 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 y task.created.
• Para comprobar su endpoint, pulse Enviar una prueba en Configuración → API y webhooks: un envío del tipo webhook.test con data vacío, firmado como los demás y enviado sean cuales sean los eventos que eligió. Como máximo uno por minuto.