L’API ZeeDo

Créez une clé dans Paramètres → API et webhooks (un propriétaire confirme d’abord son identité), puis appelez l’API avec cette clé comme jeton bearer. L’URL de base est https://api.zeedo.cloud/v1.

curl https://api.zeedo.cloud/v1/me \
  -H "Authorization: Bearer <votre clé d’API>"

• Les clés appartiennent à l’organisation, portent une portée — read, write ou admin — et peuvent être limitées à un espace de travail.
• Corps en JSON, champs en snake_case, heures au format ISO 8601 UTC.
• Les erreurs sont des documents de problème RFC 9457 : type, title, status, detail et, pour un champ refusé, errors[] avec un pointeur JSON.
• Les listes se paginent avec limit (200 au plus) et next_cursor.
• Envoyez un en-tête Idempotency-Key avec chaque POST : une répétition dans les 24 heures reçoit la même réponse que la première.
• 600 requêtes par minute et 10 flux ouverts par clé, avec les en-têtes RateLimit-*.

Une organisation enregistre une adresse de réception (Paramètres → API et webhooks, ou POST /webhooks) et choisit ses événements. Chaque événement est un POST en JSON avec des identifiants, le type et les horodatages — jamais le nom, l’e-mail ou l’adresse IP d’une personne, que vous relisez via l’API avec une clé.

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

Chaque envoi est signé : ZeeDo-Signature: t=<secondes unix>,v1=<signature>, où la signature est le HMAC-SHA256 hexadécimal de <t>.<corps brut> avec le secret de votre adresse de réception. Après une rotation du secret, l’ancien signe encore à côté pendant 24 heures, comme second v1. Refusez une signature vieille de plus de 5 minutes.

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

// header : la valeur ZeeDo-Signature ; body : le corps brut de la requête, avant toute analyse 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)));
}

• Répondez par un code 2xx en moins de 10 secondes. Toute autre réponse — une erreur, une redirection, aucune réponse — est retentée à intervalles croissants pendant 24 heures ; l’envoi devient ensuite une lettre morte, conservée 7 jours et renvoyable depuis les Paramètres.
• Les envois arrivent au moins une fois et dans n’importe quel ordre : ignorez un id déjà traité.
• Les requêtes portent aussi ZeeDo-Event-Id, ZeeDo-Event-Type et ZeeDo-Delivery-Id. Les adresses de réception sont en https, sur le port 443, à un nom d’hôte public.
• Événements : 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 et task.created.
• Pour vérifier votre adresse de réception, appuyez sur Envoyer un test dans Paramètres → API et webhooks : un envoi du type webhook.test avec un data vide, signé comme les autres et envoyé quels que soient les événements choisis. Un par minute au plus.