Die ZeeDo-API

Erstellen Sie einen Schlüssel unter Einstellungen → API & Webhooks (ein Inhaber bestätigt zuerst, dass er es selbst ist), und rufen Sie die API dann mit ihm als Bearer-Token auf. Die Basis-URL ist https://api.zeedo.cloud/v1.

curl https://api.zeedo.cloud/v1/me \
  -H "Authorization: Bearer <Ihr API-Schlüssel>"

• Schlüssel gehören der Organisation, haben einen Bereich — read, write oder admin — und können auf einen Workspace beschränkt werden.
• JSON-Bodys, Felder in snake_case, Zeiten in ISO 8601 UTC.
• Fehler sind Problem-Dokumente nach RFC 9457: type, title, status, detail und, für ein abgelehntes Feld, errors[] mit einem JSON-Pointer.
• Listen blättern mit limit (höchstens 200) und next_cursor.
• Senden Sie bei jedem POST einen Idempotency-Key-Header: Eine Wiederholung innerhalb von 24 Stunden erhält dieselbe Antwort wie der erste Aufruf.
• 600 Anfragen pro Minute und 10 offene Streams pro Schlüssel, mit RateLimit-*-Headern.

Eine Organisation registriert einen Endpunkt (Einstellungen → API & Webhooks oder POST /webhooks) und wählt ihre Ereignisse. Jedes Ereignis ist ein POST mit JSON, das IDs, den Typ und Zeitstempel enthält — nie den Namen, die E-Mail-Adresse oder die IP-Adresse einer Person; diese lesen Sie mit einem Schlüssel über die API nach.

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

Jede Zustellung ist signiert: ZeeDo-Signature: t=<Unix-Sekunden>,v1=<Signatur>, wobei die Signatur der hexadezimale HMAC-SHA256 von <t>.<Roh-Body> mit dem Geheimnis Ihres Endpunkts als Schlüssel ist. Nachdem Sie das Geheimnis rotiert haben, signiert das vorherige noch 24 Stunden daneben, als zweites v1. Lehnen Sie eine Signatur ab, die älter als 5 Minuten ist.

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

// header: der Wert von ZeeDo-Signature; body: der Request-Body im Rohzustand, vor jedem JSON-Parsen
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)));
}

• Antworten Sie innerhalb von 10 Sekunden mit einem beliebigen 2xx. Alles andere — ein Fehler, eine Weiterleitung, keine Antwort — wird 24 Stunden lang mit wachsenden Pausen erneut versucht; danach ist die Zustellung ein Dead Letter, wird 7 Tage aufbewahrt und kann unter Einstellungen erneut gesendet werden.
• Zustellungen erfolgen mindestens einmal und in keiner bestimmten Reihenfolge: Überspringen Sie eine id, die Sie schon verarbeitet haben.
• Anfragen tragen außerdem ZeeDo-Event-Id, ZeeDo-Event-Type und ZeeDo-Delivery-Id. Endpunkte sind https auf Port 443 unter einem öffentlichen Hostnamen.
• Ereignisse: 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 und task.created.
• Zum Prüfen Ihres Endpunkts drücken Sie unter Einstellungen → API & Webhooks auf „Test senden“: eine Zustellung vom Typ webhook.test mit leerem data, signiert wie jede andere und gesendet, welche Ereignisse Sie auch gewählt haben. Höchstens eine pro Minute.