Webhooks
Markdown versionGet events about your own bots in Discord, Slack or an HTTPS service you control. Webhooks are optional and unavailable until the service operator configures their dedicated encryption key.
Set up a destination
Open your dashboard settings and choose Add a webhook. Select the destination type, events, all your bots or a chosen list, and the message language. You can configure five endpoints. Only public HTTPS addresses on port 443 are accepted; private addresses and the Bluesky.bot site itself are refused.
Discord: create a webhook in your channel’s integration settings, copy its URL, then choose Discord here. Slack: create an incoming webhook for your workspace and channel, copy its URL, then choose Slack. For either provider, treat the whole URL as a password and keep it out of logs. Use Send a test after saving.
Events and data
Handle and moderation incidents; missed posting rhythms and recovery; follower milestones; certification decisions; and a daily report digest. Milestones start at 100, 250, 500, 1,000, 2,500, 5,000, 10,000, 25,000, 50,000 and 100,000 followers, then every 100,000. Each is emitted once per bot. Report digests cover the previous complete UTC day and contain counts and reasons only: never text, reporter details or exact report times.
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 | {} |
Signed JSON
Other destinations receive JSON with id, type, createdAt, apiVersion, bot (did, handle, url) and data. The raw UTF-8 body is signed. Read webhook-id, webhook-timestamp (Unix seconds) and webhook-signature. The signature is base64 HMAC-SHA256 of id.timestamp.body, using the base64-decoded bytes after whsec_. Each signature has the prefix v1,; rotation can produce two signatures separated by a space.
Copy the signing secret when it is created: it is shown once. Rotation returns a new secret and keeps the previous one valid for 24 hours. A second rotation is refused during that grace period. Store either secret only on your server. Reject timestamps more than five minutes old or in the future, compare signatures in constant time, and deduplicate by webhook-id before acting.
TypeScript verification
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 verification
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(" "))Retries and health
Return a 2xx quickly, then process your own queue. The delivery is at least once: a timeout can mean your server processed the event, so retries reuse the same id. Retries are due 1 minute, 10 minutes, 1 hour, 6 hours and 24 hours after the first attempted send, with jitter. The dispatcher runs every five minutes, so deliveries arrive within about five minutes when the queue and destination are available. Permanent 4xx responses are not retried, except 408 and 429. Redirects are never followed. There is a five-second request deadline, an 8 KB payload cap, one request in flight per endpoint, and at most 60 deliveries per endpoint per hour. Excess waits.
The settings page shows the latest results. Fifteen consecutive failed attempts spanning at least 24 hours disable the endpoint; a confirmed alert address receives one status notice. Fix the receiver, then resume it. Pausing or deleting an endpoint stops its pending notifications. A service encryption-key change disables old credentials: re-add the endpoint. URLs and signing secrets are encrypted at rest, and delivery results are kept 90 days.