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 一日分の件数と理由だけで、本文、報告者の情報、正確な時刻は含みません。
type | data |
|---|---|
handle.broken | error, since |
handle.recovered | since, recoveredAt |
moderation.flagged | severity, accountStatus, labels, since |
moderation.cleared | since, clearedAt |
liveness.missed | intervalMin, graceMin, lastActivityAt, lateSince |
liveness.recovered | lateSince, recoveredAt, lateMinutes |
followers.milestone | milestone, followers |
certification.decided | decision |
report.digest | count, 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 で検証
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 で検証
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 日間保持します。