Webhooks
Recevez les événements de vos bots dans Discord, Slack ou un service HTTPS que vous contrôlez. Cette fonction facultative reste indisponible tant que l’opérateur du site n’a pas configuré sa clé de chiffrement dédiée.
Configurer une destination
Dans les paramètres du tableau de bord, choisissez Ajouter un webhook, le type, les événements, vos bots et la langue. Cinq destinations sont possibles. Seules les adresses HTTPS publiques sur le port 443 sont acceptées ; les adresses privées et le site Bluesky.bot sont refusés.
Discord : créez un webhook dans les intégrations du canal, copiez son URL, puis choisissez Discord ici. Slack : créez un webhook entrant pour votre espace et canal, copiez son URL, puis choisissez Slack. Traitez toute l’URL comme un mot de passe et évitez de la journaliser. Après l’enregistrement, utilisez Envoyer un test.
Événements et données
Incidents de handle et de modération, retards et reprise du rythme de publication, paliers d’abonnés, décisions de certification et récapitulatif quotidien des signalements. Les paliers sont 100, 250, 500, 1 000, 2 500, 5 000, 10 000, 25 000, 50 000 et 100 000, puis tous les 100 000 abonnés. Chaque palier est émis une seule fois par bot. Les signalements concernent le jour UTC complet précédent : nombres et motifs uniquement, sans texte, renseignement sur l’auteur ou heure exacte.
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 signé
Les autres destinations reçoivent un JSON contenant id, type, createdAt, apiVersion, bot (did, handle, url) et data. Le corps UTF-8 brut est signé. Lisez webhook-id, webhook-timestamp (secondes Unix) et webhook-signature. La signature est le HMAC-SHA256 en base64 de id.timestamp.body, avec la clé décodée en base64 après whsec_. Chaque signature commence par v1, ; un renouvellement peut en produire deux, séparées par une espace.
Copiez le secret de signature à sa création : il n’est affiché qu’une fois. Le renouvellement conserve l’ancien secret valide 24 heures ; un deuxième renouvellement est refusé pendant ce délai. Conservez les secrets sur votre serveur. Refusez un horodatage passé ou futur de plus de cinq minutes, comparez les signatures en temps constant et dédupliquez avec webhook-id avant toute action.
Vérification 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)
);
});
}Vérification 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(" "))Reprises et état
Répondez rapidement avec un code 2xx, puis utilisez votre propre file. Un délai dépassé peut cacher un événement déjà traité : les reprises gardent donc le même identifiant. Les reprises sont prévues 1 minute, 10 minutes, 1 heure, 6 heures puis 24 heures après la première tentative, avec une variation aléatoire. La file est traitée toutes les cinq minutes : comptez environ cinq minutes si la file et la destination sont disponibles. Les 4xx permanents ne sont pas repris, sauf 408 et 429. Aucune redirection n’est suivie. La requête est limitée à cinq secondes et le corps à 8 Ko, avec une requête en vol et 60 envois par heure au maximum par destination ; les autres attendent.
Les paramètres montrent les derniers résultats. Quinze échecs consécutifs sur au moins 24 heures désactivent la destination ; une adresse d’alerte confirmée reçoit un avis. Corrigez le serveur puis réactivez. La pause ou suppression arrête les notifications en attente. Un changement de clé de chiffrement du service impose de recréer la destination. URL et secrets sont chiffrés au repos ; les résultats sont conservés 90 jours.