Webhook の Cast 対象サービス
Home / Act 管理 / Cast / Webhook の Cast 対象サービス

Webhook の Cast 対象サービス #

このドキュメントは開発者向けです。

概要 #

Cast 対象サービス とは Webhook Cast のアクションの URL で指定される Cast の送信先です。

このドキュメントは、Cast 対象サービスを開発・提供したい人に対して、そのために考慮しておくべき事項を提供します。

要件 #

この節では、Cast 対象サービスに課される要件について説明します。

基本的な要件 #

URL scheme は https であることが推奨されます。(RECOMMENDED)

Actcast はユーザから与えられた URL に対し 2 種類の HTTP リクエストを送出します。

  • Cast リクエスト: デバイスが Act Log を送出したものを、Actcast のサーバー経由で Cast 対象サービスに送信します。HTTP メソッドは Cast の設定に依ります。
  • Actcast option 取得リクエスト: Actcast option を取得するためのリクエストです。詳細は後述する Actcast option を参照してください。

いずれのリクエストについても、Cast 設定で設定されている HTTP ヘッダが付与されます。

Cast は何かを検知したことを誰かに通知したり、検出したデータを記録するなどの副作用を目的とすることが多いです。 そのため、Cast リクエストの HTTP メソッドは POST を用いるべきです。(SHOULD) (例えば GET を用いるべきではない理由については RFC 9205 4.5.1. を参照してください。)

Cast リクエストに対して HTTP ステータスコード 4xx および 5xx のエラーレスポンスが返された場合、リクエストは破棄され、ステータスコードが Actcast 側に記録されます。

Cast 対象サービスを利用するための URL や HTTP ヘッダは、実際にそれを Cast の URL に指定しても良いようなユーザのみがアクセスできるようにするべきです。(SHOULD) 後述する 認証 も参照してください。

Cast リクエストは Actcast のサーバーから Cast 対象サービスに送出されますが、複数のユーザ、複数の Cast が同一の Cast 対象サービスを Cast 先として指定する可能性があります。 そのため、Cast 対象サービスは IP やドメインなどのリクエスト元サーバーの情報のみに依存して rate limit などの制限をかけてはなりません。(MUST NOT) そのような制限をかける必要がある場合は、後述する 認証 の方法を用いて、より細かい単位でかけなくてはなりません。(MUST)

Actcast option #

Cast 対象サービスは Actcast に対して自身の Actcast に対する設定値を伝えることができます。 この設定値を Cast 対象サービスの Actcast option と呼びます。

例えば、Cast の分析のために全ての Cast を保存する Cast 対象サービスを提供することを考えます。 Actcast はデフォルトでは Cast 対象サービスへの負荷を減らすために Cast に対して rate limit をかけています。(Webhook Cast の rate limit) rate limit による制限がかかると全ての Cast を保存することはできないため、この Cast 対象サービスは Actcast に rate limit による制限が不要だと伝える必要があります。 これを実現するのが Actcast option です。

Actcast option は Cast 毎に判定されます。 Cast 対象サービスは 認証 の方法を用いて Actcast option を出し分けてもよいです。(MAY)

Actcast option 取得リクエスト #

Actcast は Cast 対象サービスに対して Actcast option 取得リクエストによって Actcast option を取得します。 Cast 対象サービスは Actcast option 取得リクエストに適切にレスポンスすることが推奨されます。(RECOMMENDED)

Cast 対象サービスが陽に Actcast option を宣言しようとしない場合でも、そのサービスを使おうとするユーザが Cast の設定をするのを起因として Actcast option 取得のリクエストが飛ぶことがあることに注意してください。 適切なレスポンスを返さなかった場合、Actcast option としてデフォルトの値を返したものと見做されます。

以下は Actcast option を利用する場合の要件です。

URL scheme は https でなくてはなりません。(MUST)

Actcast option 取得のリクエストのメソッドは GET です。 このリクエストに対し、以下の様なレスポンスを返す必要があります。

  • ステータスコードを問わず x-actcast-option: <base64-actcast-opiton> ヘッダをつけて返さなければならない。(MUST)
    • <base64-actcast-option> は <actcast-option> を base64 エンコーディングした文字列である。
    • <actcast-option> は次節で示す様な UTF-8 の JSON 文字列である。

いまのところ、Actcsat option 取得リクエストはユーザが Cast の設定を行ったときにのみ送出されます。 Cast 対象サービスが Actcast option を変更した場合、Cast 設定を再度行なう必要があります。

<actcast-option> #

<actcast-option> は以下の例の様な JSON です。

{
    "version": "1.0",
    "accept_ratelimit_removal": true
}

なお、これを base64 エンコーディングした文字列は ewogICAgInZlcnNpb24iOiAiMS4wIiwKICAgICJhY2NlcHRfcmF0ZWxpbWl0X3JlbW92YWwiOiB0cnVlCn0= になります。

各フィールドは以下の意味を持ちます。

フィールド名型必須内容
versionstringYesactcast-option の version。現在 “1.0” 固定。
accept_ratelimit_removalboolYesユーザに Cast 設定として「rate limit なし」を設定することを許可するか否か。

テクニック #

この節では、Cast 対象サービスを設計する上で知っておくと有用なテクニックについて説明します。

認証 #

Actcast は Cast 対象サービスの URL をユーザから受け付けます。 この URL に対してユーザがアクセス権を持つのか、Cast を投げても良いのかといったことを Actcast は検査できません。 これらは Cast 対象サービス自身が Actcast からの HTTP リクエストを認証することにより行なう必要があります。

典型的なパターンとして以下の様なものがあります。

第三者から推測されにくい URL を発行する #

ユーザに Cast 先 URL を発行させ、

https://example.com/cast-target/very-loooooooooooooooooooong-and-unguessable-url-dmVyeS1sb29vb29vb29vb29vb29vb29vb29uZy1hbmQtdW5ndWVzc2FibGUtdXJs

のような第三者から推測されにくいものを生成することで、本来利用してはいけないユーザが Cast 先として利用することを防ぐことができます。

HTTP ヘッダを利用して認証する #

Cast には URL の他に HTTP ヘッダも設定することができます。 詳細は MDN Web Docs, HTTP authentication を参照してください。

Cast に戻る