7つのイベントを、エンジンから直接
エンドポイントごとに、必要なイベントだけを購読——スパム判定からメンバーシップの変化まで。
spam.detectedmessage.suspicioususer.banneduser.kickeduser.muteduser.joineduser.leftすべてのイベントはコンパクトなJSONエンベロープで届きます。id、type、created_at、group_id、そしてイベントデータ——idはリトライをまたいで安定しているので、重複排除はセットの参照ひとつで済みます。
リトライスケジュール——実際に走るとおりに
およそ8時間で6回の試行——デプロイ、再起動、あるいは自分側の全面的な障害を乗り切るのに十分です。
0即時+1m+5m+30m+2h+6h最終試行その上に構築できる配信
少なくとも1回の配信
すべてのイベントは少なくとも1回配信されます。エンドポイントは任意の2xxで受領を確認——それ以外はすべてリトライキューに戻ります。
重複排除用の安定id
各イベントはリトライを生き延びる安定したidを持ちます。自分側での重複排除は、推測ではなく単なる参照ひとつです。
ゾンビ・エンドポイントなし
何日も失敗し続けるエンドポイントは自動的に無効化され、データに無言の欠落が生じる代わりにTelegramのDMが届きます。
テストping
本物と同じように署名されたワンクリックのテストイベント——実イベントが1つでも依存する前に、ハンドラーを検証できます。
確認できる履歴
エンドポイントごとの完全な配信履歴——試行、ステータス、タイムスタンプのすべて。受信側のデバッグに当て推量は要りません。
HTTPSのみ、つねに署名付き
エンドポイントは公開HTTPS URLでなければならず、すべてのペイロードに署名が付きます。トランスポートと作成元の両方をカバーします。
すべての配信を検証する
自分側は3行——そして誰もイベントを偽造したりリプレイしたりできません。
# X-Telm-Signature: v1=<hex>
expected = hmac_sha256(secret, timestamp + "." + body)
valid = constant_time_eq("v1=" + hex(expected), header)ポーリングではなく、プッシュ
APIのポーリングは、尋ねた時点で何が起きたかを教えてくれます。ウェブフックは、起きたその瞬間に教えてくれます。HTTPSのエンドポイントを登録し、気になるイベントを選ぶと、Telmはそれらをエンジンが動作したその秒のうちにJSONであなたのサーバーへプッシュし始めます——スパムの波、BAN、参加者の殺到まで。
すべての配信には署名が付きます。X-Telm-Signature ヘッダーには、エンドポイントのシークレットで計算した、タイムスタンプと本文のHMAC-SHA256が入っているので、あなたのサーバーは作成元と鮮度の両方をわずか3行のコードで検証できます。ペイロードはHTTPSのみで送られます。
配信は、受信側が落ちることのある現実のインターネット向けに設計されています。イベントは重複排除用の安定したidとともに少なくとも1回配信され、失敗すると段階的に広がるスケジュールでリトライします——即時、続いて1分後と5分後、30分後、2時間後と6時間後。何日も失敗し続けるエンドポイントは自動的に無効化され、無言の欠落の代わりにTelegramでメッセージが届きます。
すべては確認可能です。本番前にテストpingを送れますし、配信履歴を——試行ごと、ステータスごとに——いつでも閲覧して、自分側のパイプをデバッグできます。
よくある質問
イベントが本当にTelmから来たものだと、どう検証しますか？
各配信には X-Telm-Signature ヘッダーが付きます。これはエンドポイントのシークレットで計算した「timestamp.body」のHMAC-SHA256です。自分側で再計算して定数時間で比較し、数分より古いものは拒否すればリプレイを排除できます。
イベント発火時に自分のサーバーが落ちていたら？
Telmは段階的に広がるスケジュールでリトライします——即時、続いて1分後、5分後、30分後、2時間後、6時間後。2xxのレスポンスは配信成功として扱われます。イベントは安定したidを持つので、リトライがシステム内で重複になることはありません。
壊れたエンドポイントが永遠に配信を溢れさせることはありますか？
いいえ。成功のないまま連続で約20回失敗し、3日間まったく成功しないエンドポイントは自動的に無効化され、Telegramで通知が届きます。自分側を直したら、ワンクリックで再有効化できます。
本番前に連携をテストするには？
ダッシュボードまたはAPIから、任意のエンドポイントへテストpingを送れます——実際のイベントとまったく同じように署名付きで届きます。配信履歴には、各試行がステータスとともに表示されます。
どのプランでウェブフックを使えますか？
ウェブフックはフルAPIパッケージの一部で、ProとBusinessプランに含まれます。