Castify

Webhook によるイベント受信

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

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

注釈

すべてのフックはオプショナルです。一切登録しなくても Castify の各機能は利用可能です。 Webhook の種類とそのリクエスト内容については リファレンス を参照ください。

Castify コンソールで登録する

  1. Castify コンソールopen in new window を開き、Webhook のタブを開きます。
  2. 右上の "+" ボタンを押します。
  3. Webhook の新規作成ダイアログが開くので、以下のように入力します。
  • 識別名: (任意の名前)
  • URL: 作成したエンドポイントの URL
  • フックの種別
    • 受け取りたいイベントを指定
      • 例: 配信に制限を掛ける場合: BROADCAST_CREATE
      • 例: 視聴に制限を掛ける場合: PLAYBACK_CREATE

Webhook は複数登録することが出来ますが、 制限をかけるフックである BROADCAST_CREATE, PLAYBACK_CREATE は それぞれ１個ずつしか登録することが出来ませんので、注意してください。

カスタムデータ

Broadcast と Playback は、 その作成時にカスタムデータという任意の文字列を与えることで、 その文字列をエンティティに紐づけて保存することができます。 また、この文字列は Webhook のペイロード にも現れます。

したがって、カスタムデータを Webhook のパラメーターとすることで Webhook の振る舞いにバラエティを持たせることができます。

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

通知フックと委譲フック

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

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

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

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

性能要件

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

  • 0.5 秒以内にコネクションの確立が成功すること
  • 2.5 秒以内にレスポンスが行われること

上記の応答性能を満たなさい場合、Castify は Webhook を接続失敗 (タイムアウト) とみなし、 実行を失敗として処理します。 特に broadcastCreateopen in new window, playbackCreateopen in new window といった委譲フックの場合、 Webhook の呼び出しエラーが処理全体が失敗として扱われますので、上記の条件に注意してください。

委譲フックのリクエストが Webhook のエンドポイントに到達していた場合で、 かつ、レスポンスまでの応答時間を満たさずに失敗した場合、 Castify としては配信・視聴が生成されていないにも関わらず Webhook を受けたサービス側では、 開始の処理がトリガーされていることで、矛盾した状態となる可能性があります。

この状態による問題を避けるためには、委譲フックに対応する通知フックでステータスを更新したり、 Castify 上に配信や視聴が実際に存在するかどうかを、各種 API で確認したりといった方法があります。 整合性が重要になる場合 (配信が再度トリガーされた場合など) には Castify API を利用して状態を再確認してください。

また、ごく大規模な配信において、視聴開始フックの突発負荷を避ける必要がある場合、 視聴 Webhook の突発負荷を避ける 方法をお試しください。

最終更新日: