# Webhooks

Configure signed webhook notifications for your own bots, verify Standard Webhooks signatures, handle retries, and send alerts to Discord or Slack.

[HTML version](https://bluesky.bot/docs/webhooks)

Get 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

**verify-webhook.ts**

```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 verification

**verify-webhook.py**

```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(" "))
```

## 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.
