Webhooks

Receba eventos dos seus bots no Discord, Slack ou num serviço HTTPS que controla. A função é facultativa e permanece indisponível até o operador configurar a chave de cifra dedicada.

Configurar um destino

Nas definições do painel escolha Adicionar um webhook, o tipo, eventos, bots e idioma. São permitidos cinco destinos. Apenas são aceites endereços HTTPS públicos na porta 443; endereços privados e o próprio site Bluesky.bot são recusados.

Discord: crie um webhook nas integrações do canal, copie o URL e escolha Discord aqui. Slack: crie um webhook de entrada para o espaço e canal, copie o URL e escolha Slack. Trate o URL completo como uma palavra-passe e não o registe nos logs. Depois de guardar, utilize Enviar um teste.

Eventos e dados

Incidentes de handle e moderação, atrasos e recuperação do ritmo de publicação, marcos de seguidores, decisões de certificação e resumo diário de denúncias. Os marcos são 100, 250, 500, 1 000, 2 500, 5 000, 10 000, 25 000, 50 000 e 100 000, depois a cada 100 000 seguidores. Cada marco é emitido uma vez por bot. As denúncias abrangem o dia UTC completo anterior: apenas contagens e motivos, nunca texto, informações de quem denunciou ou horas exatas.

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 assinado

Outros destinos recebem JSON com id, type, createdAt, apiVersion, bot (did, handle, url) e data. O corpo UTF-8 original é assinado. Leia webhook-id, webhook-timestamp (segundos Unix) e webhook-signature. A assinatura é HMAC-SHA256 em base64 de id.timestamp.body, com os bytes descodificados de base64 depois de whsec_. Cada assinatura começa por v1,; a renovação pode produzir duas separadas por um espaço.

Copie o segredo de assinatura ao criá-lo: é apresentado apenas uma vez. A renovação mantém o anterior válido durante 24 horas; uma segunda renovação é recusada nesse prazo. Guarde-os apenas no servidor. Recuse datas passadas ou futuras por mais de cinco minutos, compare assinaturas em tempo constante e elimine duplicados por webhook-id antes de agir.

Verificação em 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)
    );
  });
}

Verificação em 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(" "))

Novas tentativas e estado

Responda rapidamente com 2xx e processe a sua fila. Um tempo esgotado pode esconder um evento já processado, pelo que as novas tentativas mantêm o identificador. As novas tentativas são agendadas para 1 minuto, 10 minutos, 1 hora, 6 horas e 24 horas após a primeira tentativa, com variação aleatória. A fila é processada a cada cinco minutos: os eventos chegam em cerca de cinco minutos se a fila e o destino estiverem disponíveis. Os 4xx permanentes não são repetidos, salvo 408 e 429. Não são seguidos redirecionamentos. Os limites são cinco segundos por pedido, 8 KB por corpo, um pedido em curso e 60 envios por hora por destino; os restantes aguardam.

As definições mostram os últimos resultados. Quinze falhas consecutivas durante pelo menos 24 horas desativam o destino; um endereço de alertas confirmado recebe um aviso. Corrija o recetor e retome. Pausar ou eliminar interrompe as notificações pendentes. Uma alteração da chave de cifra do serviço exige adicionar o destino novamente. URL e segredos são cifrados; os resultados são conservados 90 dias.