Telm はモデレーション イベントをあなたのサーバーにリアルタイムでプッシュできます。エンドポイントを登録し、受け取るイベントを選ぶと、Telm はそれぞれについて署名付きの POST を送ります。すべての配信は、エンドポイント シークレットで検証する HMAC-SHA256 署名 を持ちます。失敗した配信はスケジュールに沿って再試行され、恒久的に到達不能なエンドポイントは自動的に無効化されます。
1イベント エンベロープ
すべての Webhook は、共通の エンベロープ に JSON 本文を持つ HTTP POST です。エンベロープは、id(重複排除のための一意な配信識別子)、type(イベント名)、created_at タイムスタンプ、イベントが属する group_id、そしてイベント タイプに応じて形が変わる data オブジェクトを持ちます。
id は実イベントについて決定的なので、同じイベントが 2 回配信されると(たとえば再試行の後)、両方で同じ id を受け取ります。X-Telm-Delivery ヘッダー(この id を反映します)をべき等キーとして使い、ハンドラーが各イベントを一度だけ処理するようにしてください。
- エンベロープのフィールド:id、type、created_at、group_id、data。
- type は下記のカタログのイベント名の 1 つです。
- data はイベント固有のフィールドを持ちます。
- id(と X-Telm-Delivery ヘッダー)を使って再試行を重複排除します。
2イベント カタログ
エンドポイントをカタログの任意の部分集合に購読させます。spam.detected は、エンジンがメッセージをスパムとしてフラグ付けしたときに発火します。message.suspicious は monitoring モードで、エンジンが処置したはずだがメッセージをシャドウ採点しただけのときに発火します。メンバー イベントは、人の入場・退場・処置を扱います。
ping イベントは特別です。購読可能なカタログには含まれず、エンドポイントのテスト配信をトリガーしたときにのみ送られるので、レシーバーと署名チェックが端から端まで動くことを確認できます。
- spam.detected — メッセージがスパムに分類された。
- message.suspicious — シャドウ(monitoring モード)の検出。
- user.banned、user.kicked、user.muted — モデレーション アクションが適用された。
- user.joined、user.left — メンバーがグループに入場または退場した。
- ping — 手動のテスト イベント。実際のアクティビティで発火することはありません。
3イベントごとのペイロード フィールド
spam.detected と message.suspicious では、data オブジェクトが message_id、user_id、username、メッセージ テキスト(非常に長いメッセージは切り詰められます)、取られた action、category、reason、検出された language、そして confidence スコアを持ちます。message.suspicious はさらにシャドウの score を持ちます。
メンバー イベント(user.joined、user.left、user.banned、user.kicked、user.muted)では、data オブジェクトが user_id、username、first_name、任意の message_id、そして該当する場合の reason を持ちます。1 つの根本イベントが 2 つ以上の Webhook を生むことがあります。BAN をトリガーするスパム メッセージは、spam.detected と user.banned の両方として配信されます。
- スパム イベント:message_id、user_id、username、text、action、category、reason、language、confidence(message.suspicious には score も)。
- メンバー イベント:user_id、username、first_name、message_id、reason。
- 1 つの出来事が複数のイベントを発することがあります。user_id と group_id で相関づけてください。
4HMAC 署名の検証
各配信は署名されているので、それが本当に Telm から来て改ざんされていないと確認できます。エンドポイントを作成するときに一度、エンドポイント シークレット(whsec_ で始まります)を受け取ります。それを保管し、入ってくるすべてのリクエストの検証に使ってください。
検証するには、X-Telm-Timestamp ヘッダーの値を取り、ドットを付け、次に正確な生のリクエスト本文を付け、その文字列の HMAC-SHA256 を、エンドポイント シークレットをキーとして計算します。結果を hex エンコードし、v1= を接頭します。それは X-Telm-Signature ヘッダーと等しくなければなりません。定数時間比較で比べ、リプレイを防ぐためタイムスタンプが数分(5 分が良い区切りです)より古ければリクエストを拒否してください。
- X-Telm-Event — イベント タイプ。
- X-Telm-Delivery — 配信 id(べき等キー)。
- X-Telm-Timestamp — unix 秒。リプレイを防ぐため署名されます。
- X-Telm-Signature — v1= に、タイムスタンプ・ドット・生本文の hex HMAC-SHA256 を付けたもの。
5配信、再試行、自動無効化
配信は、あなたのエンドポイントが 2xx ステータスで応答した場合にのみ成功と数えられます。それ以外、つまり 2xx 以外のコード、タイムアウト、接続エラーは失敗として扱われ、固定のスケジュールで再試行されます。即座、次に 1 分後・5 分後・30 分後・2 時間後・6 時間後の 6 回の試行で、配信が失敗として閉じられるまでおよそ 8 時間半にわたります。
エンドポイントが失敗し続けると、つまり 3 日間、成功した配信なしに少なくとも 20 回連続で失敗すると、Telm はそれを自動的に無効化し、死んだ URL への送信をやめます。レシーバーが再び健全になれば、ダッシュボードから再び有効にできます。
- 成功 = HTTP 2xx。速く(約 10 秒以内に)応答し、重い作業は非同期で行ってください。
- 再試行スケジュール:即座、+1 分、+5 分、+30 分、+2 時間、+6 時間(6 回の試行)。
- 72 時間、成功なしに 20 回連続で失敗すると自動無効化されます。
- Webhook の登録には Pro プラン以上が必要です。