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