Webhook

Webhook は BroadcastPlayback 等の Castify プラットフォーム上に現れる エンティティのライフサイクルの各ステージ(作成や更新、削除)にフックを仕掛けてアプリ固有の振る舞いをプラグインするための仕組みです。

コンソール から種類ごとにフック URL を登録することができます。 フックへの通知は HTTP/HTTPS POST で行われ、HTTP の body にはイベント情報を含む JSON データが含まれます。

注釈

すべてのフックはオプショナルです。一切登録しなくても Castify の各機能は利用可能です。

Webhook の種類とそのリクエスト内容については リファレンス を参照ください。

カスタムデータ

BroadcastPlayback は、その作成時に カスタムデータ という任意の文字列を与えることで、その文字列をエンティティに紐づけて保存することができます。また、この文字列は Webhook のペイロード 上にも現れます。したがって、カスタムデータを Webhook のパラメーターとすることで Webhook の振る舞いにバラエティを持たせることができます。

カスタムデータを設定する方法はエンティティによって代わります。詳細は以下を参照してください。

通知フックと委譲フック

Webhook は大きく分けて2つのカテゴリーに分けられます。

一つは 通知フック と呼ばれるものです。これは Castify プラットフォームで起こったイベントの通知を受けるだけで、 その実行がプラットフォーム側のシステムの振る舞いに影響することはありません。

一方で 委譲フック では、それが生成したレスポンスの内容が Castify プラットフォーム側のシステムの振る舞いを変化させます。 例えば broadcastCreate のフックは、エラーレスポンスを返すことで Broadcast が実際に作成されることを防ぐことができます。 これと カスタムデータ を利用して、配信の可否の判断をカスタマイズすることができます。 同じことが playbackCreate にも言うことができ、例えば、特定の配信に対する視聴を特定のユーザー限定する、といった機能を実現できます。

通知フックはその性質上、イベントに対しての事後報告なので、その名前は 過去形の動詞 で終わります(例 broadcastCreated)。 それに対して委譲フックは 現在形の動詞 で終わります(例 broadcastCreate)。

性能要件

Webhook の応答先 URL は、以下の応答性能を保つ必要があります。

  • 500 ミリ秒以内にコネクションの確立が成功すること

  • 2500 ミリ秒以内にレスポンスが行われること

上記の応答性能を満たなさい場合、Castify は Webhook を接続失敗 (タイムアウト) とみなし、実行を失敗として処理します。 特に broadcastCreate, playbackCreate といった委譲フックの場合、 Webhook が失敗に終わった場合は、その処理全体が失敗として処理されますので、上記の条件に注意してください。

委譲フックのリクエストが Webhook URL に到達していた場合で、かつ、レスポンスまでの応答時間を満たさずに失敗した場合、 Castify としては配信・視聴が生成されていないにも関わらず、Webhook を受けたサービス側では、開始の処理がトリガーされていることで、矛盾した状態となる可能性があります。 この状態による問題を避けるためには、委譲フックに対応する通知フックでステータスを更新したり、 Castify 上に配信や視聴が実際に存在するかどうかを、各種 API で確認したりといった方法があります。 整合性が重要になる場合 (配信が再度トリガーされた場合など) には Castify API を利用して状態を再確認してください。

署名の確認

Castify から送られる Webhook リクエストには、Castify による署名が含まれています。 この値を検証することによって、イベントが第三者ではなく Castify によって送信されたことを確認できます。 Castify が呼び出す Webhook エンドポイントはインターネット上からアクセスできる必要があるため、 この署名の確認を行わない場合、第三者からの攻撃に対して無防備になる恐れがあります。

署名を検証する前に、Dashboard の Webhook設定からエンドポイントの Secret Token を取得する必要があります。 Secret token を取得したいエンドポイント内の、[Click to reveal] ボタンを選択します。

署名の確認は、以下の手順で行うことが可能です。

  1. X-Castify-Timestamp HTTP ヘッダーから timestamp を取得します。

  2. HTTP エンティティボディから JSON ペイロードを取得します。

  3. 手順 1 で得た timestamp文字列 "."手順 2 で得た JSON ペイロード の3つの値を、文字列として結合します。

  4. SHA256 ハッシュ関数を使用し、HMAC を計算します。この時、Secret Token をキーとして利用し、3 で作成した文字列をメッセージとします。

  5. X-Castify-Signature HTTP ヘッダーの文字列と比較します。

リプレイ攻撃の防止

リプレイ攻撃とは、有効なペイロード及びその署名が傍受されていた場合に、攻撃者が同一のリクエストを再度送り直すことによる攻撃手法です。

X-Castify-Timestamp HTTP ヘッダーには、Castify のサーバから送信されたイベントの発生時刻が含まれています。 この発生時刻がごく古い場合には、傍受した攻撃者によるリクエストの可能性があります。

ただし、Castify のサーバと時刻がずれている場合には、正しいリクエストを拒否してしまう可能性が出てきます。 NTP による時刻の同期を行うとともに、5分等の誤差を許容するようにすることで、NTP 障害時のエラーを防ぎつつ、攻撃者による不正なアクセスから守ることが可能です。