Webhook は、起きた瞬間にモデレーションイベントをあなたの URL にプッシュします。スパム検知、BAN、キック、ミュート、メンバーの参加・退出です。各配信は HMAC-SHA256 で署名され（whsec_ の秘密鍵に対して検証）、重複排除のための安定した配信 id を携え、サーバーに到達できない場合はスケジュールに沿って再試行されます。Webhook は Pro プラン以上の一部です。
1Webhook の役割
API をポーリングする代わりに、URL を登録すると、グループで何かが起きるたびに Telm が署名済みの HTTP POST をそこに送ります。これが、モデレーションイベントを自分のシステム（ダッシュボード、データウェアハウス、警告チャネル）にリアルタイムで取り込む方法です。
Webhook のエンドポイントは API を通じて管理します。URL を登録し、どのイベントを購読するか選び、任意で特定のグループに限定し、テストの ping を送り、最近の配信ログを読みます。
2なぜプッシュがポーリングに勝るか
タイマーでジャーナルのエンドポイントを呼び出して新しいイベントを見つけることもできますが、それはレイテンシを加え、クォータを費やし、何かが起きるまさにその瞬間を逃しかねません。Webhook はモデルを反転させます。Telm がイベントの発火した瞬間に知らせるので、あなたのシステムは数秒で反応します。
典型的な用途には、BAN を自分の管理ツールにミラーする、レイドが検知されたときにチームチャネルに警告する、検知を分析にストリームする、メンバーの参加・退出でワークフローを起動する、といったものがあります。
- リアルタイム: 次のポーリングではなく、起きたときにイベントを知ります。
- 効率的: 1 日のクォータを食う繰り返しの読み取りがありません。
- 完全: 配信は再試行されるので、あなた側の短い障害でイベントを失いません。
3購読できるイベント
購読できるイベントタイプは 7 つあり、スパム判定、罰、メンバーシップの変化をカバーします。1 つのモデレーションされたメッセージが複数のイベントを生むことがあります。BAN で終わるスパムメッセージは、spam.detected と user.banned の両方を発します。
- spam.detected — エンジンがメッセージをスパムとしてフラグ付けした。
- message.suspicious — スコア付きのシャドウ（モニタリングモード）検知。
- user.banned — メンバーが BAN された。
- user.kicked — メンバーが除去された。
- user.muted — メンバーがミュートされた。
- user.joined — メンバーがグループに参加した。
- user.left — メンバーがグループを退出した。
4ペイロードのエンベロープ
各配信は、小さく安定したトップレベルのフィールド一式と、その中のイベント固有の data オブジェクトを持つ JSON エンベロープです。詳細を必要になるまで解析せずに、type と時刻でルーティングできます。
- id — 一意の配信 id。同じイベントの再配信は同じ id を再利用し、これが重複排除の方法です。
- type — イベントタイプ、上記 7 つのいずれか。
- created_at — イベントが発火した時刻、RFC3339 UTC 形式。
- group_id — イベントが属するグループ（該当する場合）。
- data — イベント固有のオブジェクト。スパムイベントにはメッセージと判定の詳細、メンバーシップイベントにはメンバーの詳細です。
5配信が本当に Telm からのものか検証する
各配信は署名されているので、リクエストが本当に Telm から来て、途中で改ざんされていないことをサーバーが確認できます。ペイロードを信頼する前に署名を検証し、一致しないものはすべて拒否してください。
署名は、タイムスタンプと生のリクエストボディの HMAC-SHA256 で、エンドポイントの署名秘密鍵を鍵とします。検証するには、タイムスタンプヘッダーと受信した正確なバイトに対して HMAC を再計算し、署名ヘッダーと比較します。
- X-Telm-Signature — 署名。v1 に、ボディに結合したタイムスタンプの 16 進 HMAC-SHA256 が続く形式です。
- X-Telm-Timestamp — 署名される unix 秒のタイムスタンプ。古い、または再送された配信を拒否できます。
- X-Telm-Event — イベントタイプ、X-Telm-Delivery — 重複排除のための配信 id。
- 署名秘密鍵は、エンドポイント作成時に一度だけ表示され、whsec_ で始まります。安全に保管してください。配信が本物であることを証明する唯一のものです。
6信頼できる、重複排除された配信
配信は at-least-once です。Telm はイベントが必ずあなたに届くようにするので、同じイベントがときどき二度届くことがあります。すべての再配信は同じ配信 id を再利用するため、処理した id を保存して繰り返しを飛ばすことで重複排除します。
エンドポイントに到達できない、またはエラーを返す場合、配信は固定のスケジュールで再試行されます。おおよそ 1 分後、5 分後、30 分後、2 時間後、6 時間後で、約 8 時間半にわたり最大 6 回です。失敗し続けるエンドポイントは、双方を守るため自動的に無効化され、オーナーに通知されます。
- 2xx ステータスで素早く応答します。承認の後、重い処理は非同期で行います。
- 配信 id で重複排除します。ペイロードの内容では決して行いません。
- 72 時間のウィンドウ内で成功なしに約 20 回連続で失敗するエンドポイントは自動的に無効化されます。サーバーが健全になったら再度有効にします。
7エンドポイントの管理とログの読み取り
Webhook のエンドポイントは API を通じて登録・編集・削除します。作成すると署名秘密鍵をちょうど一度だけ受け取り、購読するイベントを選び、任意で特定のグループに範囲を絞ります。テスト呼び出しは署名済みの ping を送るので、実際のトラフィックが始まる前に検証が機能することを確認できます。
各エンドポイントは、何がいつ送られ、成功したかを見返せる配信ログを保持します。次のライブイベントを待たずに受信側をデバッグするのに便利です。
- エンドポイントを作成し、whsec_ の秘密鍵を直ちにコピーします。
- テストの ping を送り、署名チェックを端から端まで検証します。
- エンドポイントを 1 つのグループに絞るか、管理するすべてのグループに開いたままにします。
- 配信ログを読んで、最近の試行とその結果を確認します。
8ベストプラクティスとよくある間違い
堅牢な受信側は、最もよくある問題を防ぐいくつかのルールに従います。
- 生のボディのバイトに対して署名を検証します。先に JSON に解析して再シリアライズすると、バイトが変わってチェックが壊れることがあります。
- 素早く 2xx を返して後で処理します。遅いハンドラーはタイムアウトと無用な再試行を招きます。
- 処理を冪等にして、再配信されたイベントが二重計上されないようにします。
- 公開到達可能な URL で HTTPS を使います。Telm は内部・プライベートアドレスをブロックし、リダイレクトに従いません。
- whsec_ の秘密鍵をログやクライアントコードから遠ざけます。