イベントカタログ
すべての Webhook 配信は、イベント種別にかかわらず同じトップレベルの形をもつ 署名済みの JSON エンベロープです。Webhook を登録するときに 関心のある種別を購読してください。EvoMap は一致するイベントごとにエンベロープを POST します。
エンベロープ
json
{
"id": "evt_…",
"type": "recipe.published",
"created": "2026-06-17T12:00:00Z",
"livemode": true,
"data": { "…": "event-specific fields" }
}
| フィールド | 型 | 備考 |
|---|---|---|
id | string | 一意なイベント id（evt_…）。これで重複排除してください —— 再配信では同じ値が繰り返されます。 |
type | string | イベント種別（下の表を参照）。 |
created | string | イベントが発生した時刻の ISO-8601 タイムスタンプ。 |
livemode | boolean | 実イベントでは true、テストモードのクライアントが生成したイベントでは false。 |
data | object | イベント固有のペイロード —— 対象となったリソース。 |
livemode があるため、1 つのエンドポイントで実トラフィックと
テストモードのトラフィックを安全に扱えます。これで分岐させ、
サンドボックスのイベントが本番の状態に触れないようにしてください。
イベント種別
| 種別 | 購読可否 | 発火するタイミング |
|---|---|---|
recipe.created | ✅ | レシピの下書きが作成されたとき。 |
recipe.published | ✅ | レシピが公開バリュープールに入ったとき。 |
recipe.takedown | ✅ | 公開済みのレシピが削除されたとき。 |
ping | — | エンドポイントを検証するために自分でトリガーするテスト配信。購読可能な種別ではありません。 |
登録時の events 配列には、購読可能な種別（recipe.created、recipe.published、
recipe.takedown）から選んで指定します。ping は ping エンドポイントを明示的に
呼び出したときにのみ配信されるため、購読することはありません —— それでも
ハンドラーは受け付けられるようにしておくべきです（実イベントとまったく同様に
署名付きで届きます）。
data ペイロード
data はイベントの対象となるリソースを運びます —— recipe.* 系の種別では、
対象となったレシピです。data はオープンなオブジェクトとして扱ってください。
必要なフィールドを読み取り、追加のフィールドも許容してください。ペイロードは
破壊的変更なしに時間とともにフィールドが増える可能性があります。判断に迷う場合は、
特定の data フィールドが存在することに依存するのではなく、エンベロープの
id / type を使ってAPI経由でリソースを引き当ててください。
扱い方の指針
event.idで重複排除してください —— リトライや手動の再配信は同じ id を 再利用します。livemodeで分岐させ、テストイベントが本番データを変更しないようにしてください。- 順序を仮定しないでください —— 配信は順序が入れ替わって届いたり、リトライされたり します。ハンドラーはべき等になるよう設計してください。
関連
- Webhook —— エンドポイントの登録とイベントの購読
- Webhook のセキュリティ —— 各配信が正当なものか検証する
- 配信とリトライ —— エンドポイントが失敗したときに起きること