Webhooks

Usher puede avisar a tus servidores de lo que pasa en un entorno en el momento en que pasa: alguien se registra, inicia sesión, cambia sus datos o se va. Cada evento es un POST firmado a una dirección que eliges, y se vuelve a intentar si tu servidor no responde.

Agrega un endpoint

En Usher Console, abre el entorno y luego Webhooks → Nuevo endpoint. Indica una dirección https:// tuya y elige los eventos que debe recibir. Console muestra el secreto de firma del endpoint (whsec_…) una sola vez: guárdalo junto con los demás secretos de tu servidor.

Enviar una prueba envía un evento webhook.test solo a ese endpoint, sin importar a qué eventos esté suscrito.

Qué llega

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"
    }
  }
}

Los eventos describen personas y sesiones, nunca secretos: ni tokens, ni hashes de contraseñas, ni roles, ni el motivo por el que se bloqueó a alguien.

Comprueba cada entrega

Usher firma según la especificación Standard Webhooks, así que cualquiera de sus bibliotecas comprueba la firma por ti. Rechaza todo lo que no se verifique. Las bibliotecas también rechazan una marca de tiempo con más de cinco minutos de diferencia, para que no se pueda repetir una entrega antigua.

// 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 })
}

• Responde en menos de 15 segundos con cualquier 2xx. Cualquier otra respuesta, incluida una redirección, cuenta como un error.
• Prepárate para repeticiones. Un mensaje conserva su webhook-id en cada intento; omite los que ya procesaste.
• No dependas del orden. Los reintentos pueden llegar después de eventos más recientes.

Cuando tu servidor no responde

Usher vuelve a intentarlo a los 5 segundos, 5 minutos, 30 minutos, 2 horas, 5 horas, 10 horas y 10 horas (alrededor de un día y medio en total), y luego se da por vencido. El registro de entregas de Console muestra los intentos de cada mensaje y la última respuesta de tu servidor, y Volver a enviar inicia una entrega desde cero.

Un secreto nuevo

Nuevo secreto en Console crea otro y lo muestra una sola vez. Durante las siguientes 24 horas, cada entrega lleva dos firmas, una por secreto, para que puedas implementar el secreto nuevo sin perderte nada. Después, solo firma el nuevo.

De dónde vienen las entregas

Los webhooks salen de Usher a través de su proxy de salida, que no se conecta a direcciones privadas ni internas. Un endpoint debe ser una dirección https:// con un nombre público: no una dirección IP, un nombre privado ni una dirección en los dominios del propio Usher.