ZeeDo API

設定 → API と Webhook でキーを作成し（オーナーが先に本人確認を行います）、そのキーを Bearer 認証に使って API を呼び出します。ベース URL は https://api.zeedo.cloud/v1 です。

curl https://api.zeedo.cloud/v1/me \
  -H "Authorization: Bearer <お使いの API キー>"

• キーは組織に属し、read、write、admin のいずれかの範囲を持ち、1つのワークスペースに限定することもできます。
• 本文は JSON、項目名は snake_case、時刻は ISO 8601 の UTC です。
• エラーは RFC 9457 の問題ドキュメントです：type、title、status、detail、そして受け付けられなかった項目には JSON ポインター付きの errors[]。
• 一覧は limit（最大200）と next_cursor でページ分けします。
• すべての POST に Idempotency-Key ヘッダーを付けてください。24時間以内に同じ要求を繰り返すと、最初の応答と同じ内容を返します。
• キーごとに1分あたり600リクエスト、同時に開けるストリームは10まで。RateLimit-* ヘッダーが付きます。

組織は1つのエンドポイントを登録し（設定 → API と Webhook、または POST /webhooks）、イベントを選びます。各イベントは、ID、種類、タイムスタンプを含む JSON の POST です。人の名前、メールアドレス、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=<署名>。署名は、エンドポイントのシークレットをキーとした <t>.<未加工の本文> の HMAC-SHA256 の16進数です。シークレットを更新した後の24時間は、以前のシークレットも2つ目の 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)));
}

• 10秒以内に 2xx で応答してください。それ以外（エラー、リダイレクト、応答なし）は、間隔を広げながら24時間再試行します。その後、配信は未配信となり、7日間保管され、設定から再送できます。
• 配信は少なくとも1回行われ、順序は決まっていません。処理済みの id は読み飛ばしてください。
• リクエストには ZeeDo-Event-Id、ZeeDo-Event-Type、ZeeDo-Delivery-Id も付きます。エンドポイントは、公開ホスト名のポート443の https です。
• イベント：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 で「テストを送信」を押します。種類が webhook.test で data が空の配信が1回届きます。署名はほかの配信と同じで、選んだイベントに関係なく送られます。送信できるのは1分に1回までです。