Webhooks

O Usher pode avisar os seus servidores do que acontece num ambiente, no momento em que acontece: alguém entra, inicia sessão, altera os seus dados ou sai. Cada evento é um POST assinado para um endereço à sua escolha, repetido se o seu servidor não responder.

Adicione um endpoint

Na Usher Console, abra o ambiente e escolha Webhooks → Novo endpoint. Indique um endereço https:// seu e escolha os eventos de que deve ser avisado. A Console mostra o segredo de assinatura do endpoint (whsec_…) uma única vez: guarde-o junto dos outros segredos do seu servidor.

Enviar um teste envia um evento webhook.test só para esse endpoint, sejam quais forem os eventos a que está subscrito.

O que chega

POST /usher/webhooks HTTP/1.1
content-type: application/json
user-agent: Usher-Webhooks/1
webhook-id: msg_2fk7x…
webhook-timestamp: 1793643116
webhook-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=

{
  "type": "user.created",
  "timestamp": "2026-11-02T18:11:56.412Z",
  "data": {
    "user": {
      "id": "Qz3m…",
      "email": "lena@acme.com",
      "emailVerified": false,
      "name": "Lena Live",
      "image": null,
      "banned": false,
      "createdAt": "2026-11-02T18:11:56.380Z",
      "updatedAt": "2026-11-02T18:11:56.380Z"
    }
  }
}

Os eventos descrevem pessoas e sessões, nunca segredos: nada de tokens, nada de hashes de palavras-passe, nada de funções, nem o motivo pelo qual alguém foi bloqueado.

Verifique cada entrega

O Usher assina segundo a especificação Standard Webhooks, por isso qualquer uma das suas bibliotecas verifica a assinatura por si. Recuse tudo o que não for validado. As bibliotecas também recusam uma marca temporal com mais de cinco minutos de diferença, para que uma entrega antiga não possa ser reenviada.

// a route that receives Usher's webhooks (Node, the standardwebhooks package)
import { Webhook } from 'standardwebhooks'

const wh = new Webhook(process.env.USHER_WEBHOOK_SECRET!) // whsec_…, from Usher Console

export async function POST(request: Request) {
  const body = await request.text() // the raw body: the signature covers it byte for byte
  let event: { type: string; timestamp: string; data: Record<string, unknown> }
  try {
    event = wh.verify(body, Object.fromEntries(request.headers)) as typeof event
  } catch {
    return new Response('bad signature', { status: 400 })
  }
  // webhook-id is the same on every attempt: skip one you have handled already
  if (await alreadyHandled(request.headers.get('webhook-id')!)) return new Response(null, { status: 204 })
  await queue(event) // answer quickly; do the work afterwards
  return new Response(null, { status: 204 })
}

• Responda em 15 segundos com qualquer 2xx. Tudo o resto, incluindo um redirecionamento, conta como falha.
• Conte com repetições. Uma mensagem mantém o seu webhook-id em todas as tentativas; ignore uma que já tenha tratado.
• Não conte com a ordem. As novas tentativas podem chegar depois de eventos mais recentes.

Quando o seu servidor não responde

O Usher tenta de novo 5 segundos, 5 minutos, 30 minutos, 2 horas, 5 horas, 10 horas e 10 horas depois (cerca de um dia e meio no total) e, por fim, desiste. O registo de entregas da Console mostra as tentativas de cada mensagem e a última resposta do seu servidor, e Enviar novamente recomeça uma entrega.

Um novo segredo

Novo segredo, na Console, cria outro e mostra-o uma única vez. Durante as 24 horas seguintes, cada entrega leva duas assinaturas, uma por segredo, para que possa implementar o novo segredo sem perder nada. A partir daí, só o novo assina.

De onde vêm as entregas

Os webhooks saem do Usher pelo seu proxy de saída, que não se liga a endereços privados nem internos. Um endpoint tem de ser um endereço https:// com um nome público: não um endereço IP, um nome privado ou um endereço nos domínios do próprio Usher.