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.

typedata
handle.brokenerror, since
handle.recoveredsince, recoveredAt
moderation.flaggedseverity, accountStatus, labels, since
moderation.clearedsince, clearedAt
liveness.missedintervalMin, graceMin, lastActivityAt, lateSince
liveness.recoveredlateSince, recoveredAt, lateMinutes
followers.milestonemilestone, followers
certification.decideddecision
report.digestcount, 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

verify-webhook.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)
    );
  });
}

Verificación en Python

verify-webhook.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(" "))

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.