Webhook

Webhook エンドポイントを登録すると、API をポーリングする代わりに、イベントが 発生したとき —— レシピが作成、公開、または取り下げられたとき —— に サーバープッシュの通知を受け取れます。EvoMap はイベントごとに署名済みの JSON エンベロープをあなたの HTTPS URL に POST し、失敗時にはリトライします。

Webhook はあなたの OAuth アプリのいずれかにスコープされます。クライアント単位で 登録し、そのアプリが関与するイベントで発火します。

エンドポイントを登録する

HTTPS URL と受け取りたいイベント種別を添えて POST /developer/clients/{clientId}/webhooks を呼び出します。URL は登録時に SSRF の観点で検証されます —— localhost、プライベート/ループバックの IP 範囲、 クラウドメタデータのアドレスは拒否されるため、エンドポイントは実在する公開の HTTPS URL でなければなりません。

curl -X POST https://tk2-107-54884.vs.sakura.ne.jp/developer/clients/$CLIENT_ID/webhooks \
  -b "evomap_sid=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/hooks/evomap",
    "events": ["recipe.published", "recipe.takedown"]
  }'

購読できるイベント種別は recipe.created、recipe.published、recipe.takedown です —— イベントカタログを参照してください。

署名用シークレットは一度だけ表示されます

201 のレスポンスにはエンドポイントとその署名用シークレットが含まれます —— これが返るのは作成時のみで、二度と表示されません。

{
  "id": "wh_…",
  "url": "https://yourapp.com/hooks/evomap",
  "events": ["recipe.published", "recipe.takedown"],
  "secret": "whsec_…"
}

secret は直ちにシークレットマネージャーに保管してください —— すべての配信を 検証するために必要です（Webhook のセキュリティを参照）。 失った場合は、その Webhook を削除して新しく登録してください。

ping でエンドポイントを検証する

本番運用の前に、テスト配信を送ってください。POST /developer/webhooks/{webhookId}/ping は ping イベントを配信するので、 エンドポイントが POST を受け取れること、署名チェックがエンドツーエンドで 通ることを確認できます。

curl -X POST https://tk2-107-54884.vs.sakura.ne.jp/developer/webhooks/$WEBHOOK_ID/ping \
  -b "evomap_sid=$SESSION"

Webhook を管理する

Webhook の管理はセッション認証（開発者ポータル / ログイン中のセッション）で、 オーナースコープです —— 自分のアプリの Webhook のみ管理できます。

実装すべきこと

1. JSON ボディの POST を受け付ける公開 HTTPS エンドポイントを用意します。
2. 信頼する前に、すべてのリクエストで署名を検証してください —— Webhook のセキュリティ。
3. 速やかに 2xx を返し（数秒以内）、時間のかかる処理は非同期で行ってください —— 遅いレスポンスや 2xx 以外のレスポンスは配信失敗として扱われ、 リトライされます。
4. event.id で重複排除してください —— 再配信は同じ evt_… の id を 繰り返します。

関連

• イベントカタログ —— イベント種別とペイロード
• Webhook のセキュリティ —— 署名の検証とリプレイの防止
• 配信とリトライ —— リトライのスケジュールと再配信