Webhook

自分のボットのイベントを Discord、Slack、管理する HTTPS サービスで受け取れます。任意の機能であり、サービス運用者が専用の暗号化キーを設定するまで利用できません。

送信先を設定

ダッシュボードの設定で Webhook の追加を選び、種類、イベント、ボット、言語を指定します。送信先は五つまでです。公開 HTTPS アドレスの 443 番ポートのみ受け付け、非公開アドレスや Bluesky.bot 自身は拒否します。

Discord はチャンネルの連携設定で Webhook を作り、URL をコピーしてここで Discord を選びます。Slack はワークスペースとチャンネルの Incoming Webhook を作り、URL をコピーして Slack を選びます。URL 全体をパスワードとして扱い、ログに残さないでください。保存後にテスト送信します。

イベントとデータ

ハンドルとモデレーションの問題、投稿予定の遅れと復旧、フォロワー数の節目、認定の決定、一日分の報告のまとめを送ります。節目は 100、250、500、1,000、2,500、5,000、10,000、25,000、50,000、100,000 人で、その後は 100,000 人ごとです。各節目はボットごとに一度だけ送ります。報告は直前の UTC 一日分の件数と理由だけで、本文、報告者の情報、正確な時刻は含みません。

typedata
handle.brokenerror, since
handle.recoveredsince, recoveredAt
moderation.flaggedseverity, accountStatus, labels, since
moderation.clearedsince, clearedAt
liveness.missedintervalMin, graceMin, lastActivityAt, lateSince
liveness.recoveredlateSince, recoveredAt, lateMinutes
followers.milestonemilestone, followers
certification.decideddecision
report.digestcount, reasons
webhook.test{}

署名付き JSON

他の送信先には id、type、createdAt、apiVersion、bot(did、handle、url)、data を含む JSON を送ります。元の UTF-8 本文に署名します。webhook-id、webhook-timestamp(Unix 秒)、webhook-signature を読み取ってください。whsec_ の後ろを base64 デコードしたキーで id.timestamp.body の HMAC-SHA256 を計算して base64 化します。署名には v1, が付き、キーの更新中はスペースで区切った二つの署名があります。

署名シークレットは一度だけ表示されるので、作成時にコピーしてください。更新しても以前のキーは 24 時間有効で、その間の再更新は拒否します。サーバー側でのみ保管してください。五分以上古い、または未来の時刻を拒否し、一定時間の比較で署名を検証し、処理前に webhook-id で重複を除きます。

TypeScript で検証

verify-webhook.ts
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyWebhookEvent(
  id: string,
  timestamp: string,
  body: string,
  signatures: string,
  secret: string,
  now = Date.now(),
): boolean {
  const seconds = Number(timestamp);
  if (
    !Number.isSafeInteger(seconds) ||
    Math.abs(now / 1000 - seconds) > 300 ||
    !secret.startsWith("whsec_")
  )
    return false;
  const expected = Buffer.from(
    `v1,${createHmac("sha256", Buffer.from(secret.slice(6), "base64"))
      .update(`${id}.${timestamp}.${body}`)
      .digest("base64")}`,
  );
  return signatures.split(" ").some((signature) => {
    const received = Buffer.from(signature);
    return (
      expected.length === received.length && timingSafeEqual(expected, received)
    );
  });
}

Python で検証

verify-webhook.py
import base64
import hashlib
import hmac
import time


def verify_webhook_event(event_id, timestamp, body, signatures, secret, now=None):
    now = time.time() if now is None else now
    try:
        seconds = int(timestamp)
    except (ValueError, TypeError):
        return False
    if abs(now - seconds) > 300 or not secret.startswith("whsec_"):
        return False
    key = base64.b64decode(secret[6:], validate=True)
    message = f"{event_id}.{timestamp}.{body}".encode("utf-8")
    expected = "v1," + base64.b64encode(hmac.new(key, message, hashlib.sha256).digest()).decode()
    return any(hmac.compare_digest(expected, signature) for signature in signatures.split(" "))

再試行と状態

すぐに 2xx を返し、自分のキューで処理してください。タイムアウトでも処理済みの場合があるため、再試行は同じ ID を使います。再試行は最初の送信試行から 1 分、10 分、1 時間、6 時間、24 時間後に予定され、ランダムな変動を加えます。キューは五分ごとに処理されるため、キューと送信先が利用可能なら約五分で届きます。恒久的な 4xx は 408 と 429 を除いて再試行せず、リダイレクトも追跡しません。制限は五秒、本文 8 KB、送信先ごとに同時一件、一時間 60 件で、超過分は待機します。

設定で最近の結果を確認できます。24 時間以上にわたる 15 回連続の失敗で無効化し、確認済みの通知用メールアドレスに一度通知します。受信側を直してから再開してください。一時停止や削除で未送信の通知を停止します。サービスの暗号化キーが変わると送信先の再登録が必要です。URL とシークレットは暗号化し、送信結果は 90 日間保持します。