Webhooks

O Usher pode avisar os seus servidores sobre o que acontece em um ambiente, no momento em que acontece: alguém cria uma conta, inicia sessão, altera os seus dados ou sai. Cada evento é um POST assinado para um endereço que você escolhe, enviado de novo se o seu servidor não responder.

Adicione um endpoint

No Usher Console, abra o ambiente e vá em Webhooks → Novo endpoint. Informe um endereço https:// seu e escolha os eventos sobre os quais ele deve ser avisado. O Console mostra o segredo de assinatura do endpoint (whsec_…) uma única vez: guarde-o junto com os outros segredos do seu servidor.

Enviar teste envia um evento webhook.test só para esse endpoint, independentemente dos eventos que ele assina.

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, de hashes de senha nem de funções, e nem o motivo pelo qual alguém foi bloqueado.

Verifique cada entrega

O Usher assina conforme a especificação Standard Webhooks, então qualquer uma das bibliotecas dela verifica a assinatura por você. Recuse tudo o que não passar na verificação. As bibliotecas também recusam um timestamp com mais de cinco minutos de diferença, para que uma entrega antiga não possa ser repetida.

// 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 até 15 segundos com qualquer 2xx. Qualquer outra resposta, inclusive um redirecionamento, conta como falha.
• Espere repetições. Uma mensagem mantém o seu webhook-id em todas as tentativas; ignore as que você já processou.
• Não dependa da ordem. Novas tentativas podem chegar depois de eventos mais recentes.

Quando o seu servidor não responde

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

Um novo segredo

Novo segredo, no Console, cria outro segredo e o mostra uma única vez. Nas 24 horas seguintes, cada entrega leva duas assinaturas, uma por segredo, para que você possa implantar o novo segredo sem perder nada. Depois disso, só o novo assina.

De onde vêm as entregas

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