Standard WebhooksをChatGPTに日本語訳させた内容です。一通りチェックはしていますが、一部で不自然な表現となっている箇所があります。
原文：https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md
Webhookを簡単・安全・確実に送信するためのオープンソースツールとガイドライン
Version: 1.0.0
License: The Apache License, Version 2.0.
Introduction｜はじめに
Webhookは今や広く利用されており、世界中の多くのトップ企業が自社APIの利用者にイベントを送信する手段として採用しています。
しかし現在、このエコシステムは分断されており、各プロバイダー（Webhook提供者）が異なる実装や品質で運用しています。
たとえ高品質な実装であっても互換性はなく、統一された仕組みが存在しません。
この分断は、提供者・利用者の双方に負担を与え、イノベーションの妨げとなっています。
利用者にとっては、提供者ごとに異なるWebhookの扱いを理解し直し、認証方法を覚え直し、独自実装による"gotchas(落とし穴)"に対処する必要があります。
提供者にとっても、セキュリティや将来互換性といった既に解決済みの課題を再び解決しなければならない状況です。
私たちは、この問題に対してシンプルな解決策を提案します。
それは「業界全体で "Webhook" を標準化すること」です。
本設計ドキュメントでは、既存の業界ベストプラクティスをもとに策定した厳格なWebhookガイドライン「Standard Webhooks」を提案します。
私たちは、「Standard Webhooks」が、JWTがAPI認証にもたらした変革と同じ役割を、Webhookにもたらすと信じています。
一貫性があり、さまざまな実装でサポートされる共通プロトコルを採用することで、これまでの課題を解消し、Webhookエコシステムにおける新たなツールやイノベーションを促進できるでしょう。
この実現に向けて、私たちはオープンソースで、コミュニティ主導のWebhook送信ツールとガイドラインを開発しました。
What are Webhooks?｜Webhooksとは？
Webhook は HTTP コールバックの一般的な呼び方であり、サービス同士がイベントを通知し合う仕組みです。Webhooks はサービスの API の一部ですが、「逆向きの API」と考えることもできます。クライアントがサービスにリクエストを送りたいときは API 呼び出しを行い、サービスがクライアントにイベントを通知したいときは Webhook をトリガーします（例:「ユーザーが支払いをした」「タスクが完了した」など）。
Webhooks はサーバー間通信です。つまり、上記の例において顧客とサービスの両方が HTTP サーバーを運用しており、一方は API 呼び出しを受け取り、もう一方は Webhook を受け取ります。重要なのは、Webhook は通常の API と共存することが多いものの必須ではなく、従来型 API を提供せずに Webhook だけを送信するサービスもあるという点です。
Design Goals｜設計目標
以下は、この仕様の設計と開発を導く原則と目標です。
- Secure.（安全性）: 安全な実装を簡単にし、不安全な実装を難しくする
- Reliable.（信頼性）: Webhook が頼れるものであるためには、信頼できるものでなければならない
- Interoperable.（相互運用性）: 異なる提供者・利用者・ツール間での互換性と相互運用性を実現する必要がある
- Simple.（シンプル）: シンプルさが重要であり、既存システムに不要な複雑さを加えてはならない
- Backward and forward compatible.（後方互換性と前方互換性）: 既存の Webhook 実装とも将来の実装とも並行して動作できるようにする必要がある
Specification｜仕様
Standard Webhooks 仕様は、Webhook の生産者（送信者）が従うべき一連の規約であり、Webhook の利用者（受信者）に対して安全で一貫性があり、相互運用可能なインターフェースを提供することを目的としています。この仕様には、互換性のある実装に必須の要件と、必須ではないが提供者・利用者の双方により良い体験をもたらす推奨事項が含まれています。
Payload｜ペイロード
ペイロードはすべての Webhook の中核部分です。Webhook の一部として送信される実際のデータであり、通常はイベントや関連情報に関する重要な情報で構成されます。
この仕様ではペイロードの構造、形式、内容について強制はしませんが、推奨事項を提示しています。
Payload structure｜ペイロードの構造
- ペイロードは HTTP ボディに渡されるべきです。
- ペイロードは最大限の互換性のため JSON形式 が推奨されますが、他のコンテンツタイプも使用可能です。
- 各イベントタイプごとにペイロード構造の例を提供し、さらに JSON Schema や OpenAPI などで形式的な仕様を示すことが推奨されます。
- ペイロード構造:
-
type: イベントに関連するドット区切りのタイプ。送信されるイベントの種類（例:"user.created"や"invoice.paid"）、およびペイロード（データ）のスキーマを示し、階層的にグループ化されるべきです。 -
timestamp: イベントが発生した時刻（必ずしも配信時刻と同じではない）。 ISO 8601 formatted で表記されるべきです。 -
data: イベントに関連する実際のデータ。dataプロパティの一部として渡すか、トップレベルオブジェクトにまとめることも可能です。 - 追加のメタデータは、トップレベルのプロパティとして、または
dataの一部として追加できます。
-
ペイロード例:
{
"type": "example.event",
"timestamp": "2022-11-03T20:26:10.344522Z",
"data": {
"foo": "bar",
"fizzbuzz": 2
}
}
"Thin" vs "Full" payloads
Webhook のペイロードには大きく分けて2つのアプローチがあります。「Full」ペイロードと「Thin」ペイロードです。Fullペイロードはイベントに関する完全な情報、関連エンティティの状態、変更点すべてを含みます。一方、Thinペイロードは影響を受けたエンティティの識別子と、場合によっては変更に関する情報のみを含みます。
架空のアドレス帳管理サービスを考えてみましょう。これは、アドレス帳を更新・管理でき、データが変更されるたびに Webhook を送信するシンプルなサービスです。
ここで新しい連絡先を作成したと仮定します。その場合に送信されるペイロードは次のようになります。
Fullペイロード:
{
"type": "contact.created",
"timestamp": "2022-11-03T20:26:10.344522Z",
"data": {
"id": "1f81eb52-5198-4599-803e-771906343485",
"type": "contact",
"fullName": "John Smith",
"address": "800 W NASA Pkwy, Webster, TX 77598, USA",
"phoneNumber": "(281) 332-2575",
"birthday": "1980-04-19",
"occupation": "Engineer, ACME"
}
}
Thinペイロード:
{
"type": "contact.created",
"timestamp": "2022-11-03T20:26:10.344522Z",
"data": {
"id": "1f81eb52-5198-4599-803e-771906343485"
}
}
薄いペイロードとフルペイロードは二者択一ではありません。例えば「Thin」方式を採用しつつ、"fullName"フィールドのように頻繁に利用され便利なものだけを含めることもできます。
両者には長所と短所があり、どちらを選ぶかは具体的な要件に依存します。
Fullペイロードを使う主な利点は、Webhook の利用者が追加の API 呼び出しを行わなくても、ほとんどの情報が得られる点です。
一方でThinペイロードは、性能面で優れており（送信・生成データ量が少ない）、柔軟性も高く（コードのあらゆる場所からフルデータを取得するのは簡単ではない）、さらに将来性も高い（薄いものをフルにすることはできるが、その逆は困難）。薄いペイロードのもう一つの重要な利点は、データフローの制御がしやすい点です。
多くのシナリオでは、特定のデータにアクセスした際に監査ログを残すことが望ましい（あるいは必須）です。フルペイロードではデータがすべての受信エンドポイントに送信されますが、薄いペイロードでは利用者が必要なデータを明示的に問い合わせる必要があるため、アクセスの監査や制限が可能になります。
Payload size｜ペイロードサイズ
Webhook ペイロードのサイズに技術的な制限はありませんが、通常は 20kb 未満の小さいサイズに保つことが推奨されます。これには複数の理由がありますが、主な理由は Webhook の送信者として受信者に不要な負荷を与えることになるからです。受信者は特定のイベントに関心がないかもしれず、送られてくるすべてのデータに興味があるわけではありません。ペイロードサイズを小さく保つことで、制御権を受信者側に委ねることができます。
大量のデータ（例: 画像やその他のアセット）を送信する必要がある場合は、どこかにアップロードして Webhook でリンクを渡すか、データが動的な場合は参照すべきリソースや URL のみを含めることを検討してください。
Verifying webhook authenticity｜Webhookの真正性検証
Webhook は未知の送信元からの単なる HTTP リクエストであるため、その真正性を検証することは安全な Webhook 実装において必須です。
Webhook の真正性を検証する方法はいくつかあり、より優れた方法も存在します。Webhook の真正性を検証する最も一般的な方法は、事前共有された秘密鍵を用いた HMAC 署名であり、代替手段として非対称署名（詳細は後述）を使う方法もあります。
セキュリティではよくあることですが、署名検証に正しい暗号プリミティブを使用するだけでは、安全な実装には不十分です。このセクションでは、シンプルかつ安全な実装を実現するためのセキュアな方式と追加のガイドラインを示します。
Webhook metadata｜Webhookメタデータ
ペイロードに加えて、Webhook の実装には多くの場合、2つの重要なメタデータが含まれます。試行のタイムスタンプと、Webhook に関連付けられた一意の識別子です。セキュアな署名方式では、ペイロードだけでなく、追加メタデータ（タイムスタンプと一意識別子）の真正性も検証する必要があります。
試行タイムスタンプとは、Webhook の送信が行われた時刻を指します。この試行タイムスタンプは、イベントが発生した時刻とは異なる場合があります。よくある例として「配信失敗」があります。Webhook が再試行されるたびに試行タイムスタンプは更新されますが、元のイベントのタイムスタンプは変わりません。試行タイムスタンプは、リプレイ攻撃を防ぐための重要なセキュリティ対策です。
一意識別子は、特定のイベントに紐づいた固有の ID であり、Webhook が何度リトライされても変わりません。この ID はしばしば冪等性キーとして使用され、悪意・誤り・ネットワーク問題により同じイベントが複数回送信されても、利用者側で一度だけ処理することを保証できます。
Signature scheme｜署名方式
前述のとおり、Webhook の本文と関連するメタデータの両方に署名することが重要です。これを実現するために、メッセージの ID・タイムスタンプ・本文を（ピリオドで区切って）連結し、それに署名します。
したがって署名対象の内容は msg_id.timestamp.payload となります。
例:
msg_2KWPBgLlAfxdpx2AI54pPJ85f4W.1674087231.{
"type": "contact.created",
"timestamp": "2022-11-03T20:26:10.344522Z",
"data": {
"id": "1f81eb52-5198-4599-803e-771906343485"
}
}
あるいは、実際には最小化された JSON（送信されるのがそれだと仮定）で:
msg_2KWPBgLlAfxdpx2AI54pPJ85f4W.1674087231.{"type":"contact.created","timestamp":"2022-11-03T20:26:10.344522Z","data":{"id":"1f81eb52-5198-4599-803e-771906343485"}}
メッセージ ID とタイムスタンプはユーザーが制御できないようにすること、少なくとも . を含められないようにすることが重要です。これは特定の攻撃を防ぐためです。
送信時に JSON 本文を最小化するのは問題なく、むしろ推奨されますが、送信されるペイロードと署名対象のペイロードが同一であることが重要です。暗号署名はわずかな違いにも敏感で、スペースひとつで署名が無効になることがあります。これは非常に一般的な失敗パターンで、多くの Webhook 受信者が本文を JSON としてパースした後、再度シリアライズしてしまい、JSON のシリアライズ結果の微妙な違い（実装間、さらには同じ実装内でも再実行で異なる場合がある）により検証が失敗することがあります。
本仕様は対称署名と非対称署名の両方を許容しており、どちらを使うかによって若干異なる処理が必要になる場合があります。使用方法に制限はなく、例えばある受信者は対称署名を使い、別の受信者は非対称署名を使うこともでき、同じ受信者が両者を切り替えることも可能です。
対称署名と非対称署名にはいくつかの違いがあり、その使用方法も異なります。
| 対称署名 (Symmetric) | 非対称署名 (Asymmetric) | |
|---|---|---|
| 署名方式 | HMAC-SHA256 |
ed25519 |
| 秘密鍵 | ランダム生成、24バイト (192ビット)〜64バイト (512ビット) | 標準的な ed25519 鍵ペア |
| 秘密鍵シリアライズ | base64 エンコード、識別しやすいように whsec_ プレフィックス |
base64 エンコード、秘密鍵は whsk_、公開鍵は whpk_ プレフィックスで識別 |
| 署名識別子 | v1 |
v1a |
比較:
-
対称署名:
- 高速。HMAC-SHA256 は高速で、しばしばハードウェアによる最適化もされており、非対称方式よりもはるかに速い。
- シンプル。非対称署名に比べてはるかに簡単に導入できる。
- 普及度。HMAC-SHA256 はすべてのプラットフォームや言語で広く利用可能。
- 注意点。署名鍵は他の暗号秘密と同様に扱う必要がある。もし送信者と受信者双方のセキュリティを完全に制御できない場合は、非対称署名を推奨。
-
非対称署名:
- 追加のセキュリティ層を提供できる。秘密鍵にアクセスするのは送信者だけでよい。
- 受信者は公開可能な（非秘密の）鍵で署名を検証でき、セキュリティが大幅に向上する。
- 性能面。署名の生成・検証は対称方式に比べて CPU 負荷が高い場合がある。
「秘密鍵シリアライズ」の行は、顧客に提示する際のシリアライズ形式を指します。一貫性のあるシークレット形式を持つことで、追加設定なしで正しい方式を正しく利用でき、鍵が意図した通りに使われることを保証できます。
「署名識別子」は、署名をシリアライズして顧客に渡す際に付与されるバージョン識別子です（詳細は「Webhook ヘッダー」セクションで説明）。対称署名は v1、非対称署名は v1a がプレフィックスとして付与されます。例えば、対称署名では v1 に続けてカンマ（,）、その後に base64 エンコードされた署名が続きます。
例: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
Additional considerations｜追加の考慮事項
- 対称署名の場合、署名鍵はエンドポイントごとに一意であるべきです。非対称署名の場合もエンドポイントごと（または顧客ごと）に一意であるべきです。鍵を複数の顧客で使い回すとセキュリティ問題につながります！
- 対称署名よりも非対称署名を優先することを推奨します。対称署名の性能上の利点と、セキュリティ上の欠点を比較検討してください。
- 鍵の配布方法については、利用者と提供者間で早い段階から検討する必要があります。
- 受信者は公開鍵と署名方式の信頼リストを構築すべきです。信頼できない公開鍵（例: リクエストの追加ヘッダーから読み取った公開鍵）で生成された署名を盲目的に信用してはいけません。
Webhook headers (sending metadata to consumers)｜Webhookヘッダー（利用者へのメタデータ送信）
前述のとおり、Webhook のペイロードは HTTP POST リクエストの本文として送信されるべきであり、それに付随する追加データはヘッダーとして送信される必要があります。
すべてのヘッダーは webhook- をプレフィックスとし、以下の正確な名称に従うべきです。
ヘッダー一覧:
-
webhook-id: 上記のセクションで説明した一意の Webhook 識別子 -
webhook-timestamp: 整数型の UNIX タイムスタンプ（エポックからの秒数） -
webhook-signature: この Webhook の署名
署名ヘッダーは、この Webhook に関連する署名をスペース区切りで並べたリストです。1つの署名だけでなくリスト形式になっている理由は、ダウンタイムゼロでのシークレットのローテーションをサポートするためです。署名に使う秘密鍵は通常は変更されるべきではありませんが、（侵害など）状況によって変更が必要になる場合があります。ダウンタイムゼロでのシークレットローテーションをサポートすることで、Webhook の運用がローテーション中も影響を受けません。
これを実現するために、Webhook は現在の鍵と古い鍵（一定期間のみ有効）で署名され、両方の署名が webhook-signature ヘッダーにスペース区切りで含まれます。Webhook の受信者は、いずれかが一致するまで複数の署名を検証できます。複数の鍵（侵害されたものを含んでも）で署名しても、受信者は有効な署名を必要とするため、方式のセキュリティは低下しません。
ヘッダー例:
webhook-id: msg_2KWPBgLlAfxdpx2AI54pPJ85f4W
webhook-timestamp: 1674087231
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4= v1a,hnO3f9T8Ytu9HwrXslvumlUpqtNVqkhqw/enGzPCXe5BdqzCInXqYXFymVJaA7AZdpXwVLPo3mNl8EM+m7TBAg==
Verifying signatures｜署名の検証
署名の検証は生成と似ていますが、いくつか考慮すべき点があります。
- 対称署名を検証する際は、計算結果と期待される署名を比較するのに定数時間比較関数を使用してください。これを怠るとタイミング攻撃を受けやすくなり、受信者が署名オラクルとして悪用される可能性があります。
- 非対称署名を検証する際は、十分に実績のある暗号ライブラリを使用してください。この依存関係は常に最新に保つ必要があります。
-
webhook-timestampヘッダーが現在のタイムスタンプと許容範囲内であることを確認し、リプレイ攻撃を防止してください。 -
webhook-idヘッダーを冪等性キーとして使用し、同じ Webhook を誤って複数回処理しないようにしてください（例: ID を redis に5分間保存）。
Operational considerations｜運用上の考慮事項
前のセクションでは署名方式、ペイロード、ヘッダーに関する重要な考慮事項を扱いました。本セクションでは、良い Webhook 体験に必要な運用上の考慮事項について説明します。
Event types｜イベントタイプ
イベントタイプは、Webhook で送信されるイベントの種類とペイロードのスキーマを示します。あるイベントタイプに関連付けられたペイロードは、常に同じスキーマを持つべきです。イベントタイプは、REST における異なる URL パスと考えることができます。REST API が特定の URL に対して常に決まったスキーマを期待し返すように、Webhook もそうあるべきです。
イベントタイプは階層的で、ドット区切りの識別子リストとしてフォーマットすることが推奨されます。また、識別子は [a-zA-Z0-9_] に制限するべきです。これは API で使用されるイベントタイプ ID を指しますが、よりユーザーフレンドリーな表示文字列の使用を制限するものではありません。例えば、イベントタイプを user.created とし、表示文字列を「ユーザーが作成されました」とすることができます。
Webhook の利用者が、どのエンドポイントでどのイベントタイプを受け取りたいかを選択できるようにし、送信側でフィルタリングを行うことが推奨されます。これにより、利用者が興味のないイベントを受け取ることによる不要な負荷が大幅に減少します。
Deliverability and reliability｜配信可能性と信頼性
Webhook 実装が信頼され、頼れるものとなるためには、Webhook をタイムリーかつ確実に配信するために可能な限りの対策を行う必要があります。
Webhook の送信は失敗する場合があります。これはネットワークの問題、受信者側のバグ、その他さまざまな要因によって発生します。したがって、Webhook の送信者は成功するまで、または配信が不可能であると判断されるまで再送を試みる責任があります。リトライは信頼性のある Webhook 運用において重要な要素です。
複数日にわたるリトライスケジュールを設け、指数バックオフ方式で再送することが推奨されます。また、Webhook 試行自体による再発的な負荷で失敗するのを防ぐために、リトライにはランダムなジッターを加えることが推奨されます。
場合によっては、Webhook 配信が長期間にわたり継続的に失敗することもあります。そのような場合には、別の手段（例: メール）で利用者に通知することが重要であり、対象エンドポイントへの今後の配信を無効化することが推奨されます。
リトライスケジュール例:
| 遅延時間 | 開始からの経過時間 |
|---|---|
| 即時 | 00:00:00 |
| 5秒後 | 00:00:05 |
| 5分後 | 00:05:05 |
| 30分後 | 00:35:05 |
| 2時間後 | 02:35:05 |
| 5時間後 | 07:35:05 |
| 10時間後 | 17:35:05 |
| 14時間後 | 31:35:05 |
| 20時間後 | 51:35:05 |
| 24時間後 | 75:35:05 |
Delivery success and failure｜配信成功と失敗
Webhook 配信は 2xx ステータスコード（200〜299）で応答された場合に成功とみなし、それ以外のシナリオでは失敗とみなします。失敗の例としては、non-2xx のレスポンスコード（例: 404、500）、リクエストタイムアウト（次のセクション参照）、接続リセットなどがあります。
Webhook を送信する際は HTTP のエチケットを守り、HTTP ステータスコードに適切に対応することが重要です。推奨されるステータスコードの扱いは次のとおりです:
-
2xx: 成功。 -
3xx: 失敗。リダイレクトを追跡すると送信者・受信者双方に不要な負荷がかかるため、Webhook URL を更新することを推奨します。 -
410 Gone: サーバーがこの送信元からの Webhook を受け取る意思がないことを示します。送信者は Webhook エンドポイントを無効化し、メッセージ送信を停止すべきです。 -
429 Too Many Requests: レート制限に達したことを示し、追加リクエストを制御することが推奨されます。 -
502 Bad Gateway及び504 Gateway Timeout: どちらも通常はサーバーが過負荷状態であることを示すため、リクエストを制御することが推奨されます。 - その他のステータスコードはすべて失敗として扱うべきです。
さらに、一部のレスポンスには retry-after ヘッダー（例: 503 Service Unavailable）が含まれることがあり、次回の再試行スケジュールで考慮すべきです。
Request timeouts｜リクエストタイムアウト
Webhook を確実に配信するためには、受信者がリクエストを処理し応答するのに十分な時間を確保することが重要です。Webhook のリクエストタイムアウト値は 15〜30 秒程度が推奨されます。
Enforcing HTTPS｜HTTPS の強制
送信される Webhook の内容によっては、すべての Webhook エンドポイントを HTTPS にすることが望ましい場合があります。上記の署名方式はペイロードの真正性と完全性を保証します（改ざんは防げます）が、データを暗号化するわけではないため、盗聴されてペイロード内容を閲覧される可能性があります。
Static source IPs｜固定送信元 IP
Webhook 受信者の中には、エンドポイントの前にファイアウォール（または他のセキュリティ機構）を設置し、あらかじめ定義された固定 IP アドレスからの Webhook しか通過できないようにしている場合があります。これは多くの企業環境で一般的であり、Webhook の必須要件ではありませんが、よくある考慮事項です。
Server side request forgery (SSRF)｜サーバーサイドリクエストフォージェリ
サーバーサイドリクエストフォージェリ（SSRF）攻撃とは、攻撃者がサーバー上の機能を悪用して内部リソースを読み取ったり更新したりする攻撃です。この攻撃では、攻撃者がサーバーが呼び出す URL を与えたり改変したりします。攻撃者が URL を巧妙に選ぶことで、AWS メタデータのようなサーバー設定を読み取ったり、HTTP 対応データベースなどの内部サービスに接続したり、公開を意図していない内部サービスに POST リクエストを送信できてしまう可能性があります。
Webhook の実装は SSRF に特に脆弱です。なぜなら、利用者（顧客）が任意の URL を追加でき、それが内部 Webhook システムから呼び出されるためです。
SSRF を防ぐ主な方法は、Webhook が内部ネットワークやサービスを呼び出せないようにすることです。これを実現するには2つの対策が有効です。1つ目は、すべての Webhook リクエストを内部 IP アドレスをフィルタする専用プロキシ（例: smokescreen）経由で処理すること。2つ目は、Webhook ワーカー（またはプロキシ）を内部サービスにアクセスできない専用のプライベートサブネットに配置することです。
Additional References｜参考情報
Additional functionality｜追加機能
このセクションでは、Webhook 実装における必須要件ではないものの、送信者・受信者の双方に大きな利点をもたらす追加機能について説明します。
Multiple endpoints (fanout)｜複数エンドポイント（ファンアウト）
Webhook 受信者が複数の場所で Webhook を受け取りたいと考えるのは一般的です。例えば、invoice.paid イベントをユーザー管理システム（顧客の機能を有効化するため）、CRM（営業チームを更新するため）、チームのコミュニケーションアプリ（チームで祝うため）で受け取りたい場合があります。そのため、顧客が複数の Webhook エンドポイントを追加できるようにし、同じ Webhook を複数の宛先で受け取れるようにすることが推奨されます。
Visibility into failures and manual retries｜失敗の可視化と手動リトライ
Webhook はさまざまな理由で失敗する可能性があり、失敗の可視性が不十分だと、利用者はサービスの低下や障害をデバッグできなくなることがあります。そのため、Webhook 送信者が顧客に対して失敗したメッセージの一覧や失敗理由を確認する手段を提供するのは一般的です。さらに、利用者が特定の Webhook や一定範囲の失敗を手動で再送できるようにすることは非常に重要です。これにより、長期的な障害から復旧してもメッセージ配信の欠落を防ぐことができます。
Endpoint management API｜エンドポイント管理API
Webhook エンドポイントを追加・削除・一覧できる API を用意することで、Webhook 利用者やサードパーティ開発者が Webhook を基盤とした自動化を構築できるようになります。よくあるユースケースの一つとして、ワークフロー自動化ツールがユーザーによるワークフロートリガーの追加・削除に応じて、特定のイベントタイプを持つ Webhook エンドポイントを自動的に追加する仕組みがあります。
Migrating to Standard Webhooks｜Standard Webhooksへの移行
Standard Webhooks は既存のレガシーな Webhook 実装や署名方式と並行してサポート可能であり、利用者のワークフローや稼働中の統合に中断をもたらすことはありません。
Standard Webhooks に移行するには、前述の署名方式に従い、既存のヘッダーに加えて Standard Webhooks ヘッダーを追加するだけで十分です。既存のヘッダーを削除せずに追加ヘッダーを付与することで、既存サービスに中断が発生するのを防げます。既存の Webhook 署名シークレットはレガシー方式と Standard Webhooks の両方で再利用できるため、秘密鍵を変更する必要もありません。
本ドキュメントで述べられているその他の推奨事項や要件も、既存の実装と並行して追加でき、干渉することはありません。
Migrating the payload｜ペイロードの移行
ペイロードの移行は任意であり、それを行わなくても Standard Webhooks の互換性による利点の大部分を享受できます。しかし、移行を行うことで Standard Webhooks エコシステムをさらに活用できるようになるため、推奨されます。
ペイロード移行にはいくつかの戦略があり、それぞれに利点と欠点があります。1つ目は、既存のペイロードに新しいフォーマットのデータを追加する方法です。この方法は簡単で後方互換性もありますが、混乱を招いたり、データの冗長性につながったりする可能性があります。2つ目は改良版で、データを重複させますが、それは切り替え前に作成されたエンドポイントに限られます。最後の方法は、既存のイベントごとに新しいイベントタイプを作成し、それらを新しいフォーマットに準拠させる方法です。