Webhooks
Recibe eventos de tus propios bots en Discord, Slack o un servicio HTTPS que controles. Es opcional y no estará disponible hasta que el operador configure la clave de cifrado dedicada.
Configurar un destino
En los ajustes del panel elige Añadir un webhook, el tipo, eventos, bots e idioma. Se permiten cinco destinos. Solo se aceptan direcciones HTTPS públicas en el puerto 443; se rechazan las privadas y el propio sitio Bluesky.bot.
Discord: crea un webhook en las integraciones del canal, copia su URL y elige Discord aquí. Slack: crea un webhook entrante para tu espacio y canal, copia su URL y elige Slack. Trata la URL completa como una contraseña y no la registres en los logs. Después de guardar, usa Enviar una prueba.
Eventos y datos
Incidentes de handle y moderación, retrasos y recuperación del ritmo de publicación, hitos de seguidores, decisiones de certificación y resumen diario de reportes. Los hitos son 100, 250, 500, 1.000, 2.500, 5.000, 10.000, 25.000, 50.000 y 100.000; luego cada 100.000 seguidores. Cada hito se emite una vez por bot. Los reportes cubren el día UTC completo anterior: solo recuentos y motivos, nunca texto, datos del denunciante ni horas exactas.
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 firmado
Otros destinos reciben JSON con id, type, createdAt, apiVersion, bot (did, handle, url) y data. Se firma el cuerpo UTF-8 original. Lee webhook-id, webhook-timestamp (segundos Unix) y webhook-signature. La firma es HMAC-SHA256 en base64 de id.timestamp.body, usando los bytes base64 decodificados tras whsec_. Cada firma empieza por v1,; al renovar puede haber dos separadas por un espacio.
Copia el secreto de firma al crearlo: solo se muestra una vez. Al renovarlo, el anterior sigue siendo válido 24 horas; se rechaza una segunda renovación durante ese plazo. Guárdalos solo en tu servidor. Rechaza fechas más de cinco minutos pasadas o futuras, compara las firmas en tiempo constante y deduplica por webhook-id antes de actuar.
Verificación en 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)
);
});
}Verificación en 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(" "))Reintentos y estado
Devuelve un 2xx rápidamente y procesa tu cola. Un tiempo agotado puede ocultar un evento ya procesado, así que los reintentos usan el mismo identificador. Los reintentos se programan a 1 minuto, 10 minutos, 1 hora, 6 horas y 24 horas del primer intento, con variación aleatoria. La cola se procesa cada cinco minutos: los eventos llegan en unos cinco minutos si la cola y el destino están disponibles. No se reintentan los 4xx permanentes salvo 408 y 429. No se siguen redirecciones. El límite es cinco segundos por petición, 8 KB por cuerpo, una petición en curso y 60 envíos por hora y destino; los demás esperan.
Los ajustes muestran los últimos resultados. Quince fallos seguidos durante al menos 24 horas desactivan el destino; una dirección de alertas confirmada recibe un aviso. Corrige el receptor y reanúdalo. Pausar o eliminar detiene las notificaciones pendientes. Un cambio de clave de cifrado del servicio exige volver a añadir el destino. URL y secretos se guardan cifrados; los resultados se conservan 90 días.