Webhooks

Usher puede avisar a tus servidores de lo que pasa en un entorno en cuanto 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 tú, que se vuelve a intentar si tu servidor no responde.

Añade un endpoint

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

Enviar una prueba envía un evento webhook.test solo a ese endpoint, esté suscrito a lo que esté.

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 de un bloqueo.

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 cosa, redirecciones incluidas, cuenta como un fallo.
• Cuenta con repeticiones. Un mensaje conserva su webhook-id en cada intento; sáltate los que ya hayas procesado.
• No dependas del orden. Los reintentos pueden llegar después de eventos más recientes.

Cuando tu servidor no responde

Usher vuelve a intentarlo al cabo de 5 segundos, 5 minutos, 30 minutos, 2 horas, 5 horas, 10 horas y otras 10 horas (en total, aproximadamente un día y medio), y después se rinde. El registro de entregas de Console muestra los intentos de cada mensaje y la última respuesta de tu servidor, y Volver a enviar empieza una entrega desde cero.

Un secreto nuevo

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

De dónde vienen las entregas

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