Webhooks

Block-Auth llama a tu backend cuando algo cambia fuera de tu app: un usuario cierra su sesión o desvincula su cuenta desde Block-Auth Identity. Úsalo para cerrar tu propia sesión o eliminar el vínculo.

Configura la URL

En el Dashboard, abre tu app y rellena el tercer campo de URL. Se llama Cuando falla el inicio de sesión, pero es la URL del webhook. Consulta URL del webhook.

Escribe una ruta, como /auth/blockauth/webhook, o una URL completa. Una ruta se envía a https:// más el dominio de tu app.
La URL debe usar https y estar en el dominio validado de tu app. Cualquier otro host se ignora.
Los webhooks solo van al dominio propio de tu app, no al dominio automático de desarrollo (*.block-auth.io). Para probarlos, usa una app cuyo dominio apunte a un servidor que controles.
No uses /signout/callback: es el valor por defecto y significa «sin webhook».

Eventos

`event`	Cuándo	Qué hacer
`signout`	El usuario cierra su sesión de tu app desde Identity o desde el widget, o tu backend llama a `/api/auth/signout` y el usuario tenía sesiones en otros dispositivos.	Cierra la sesión de ese usuario en tu app.
`account.unlinked`	El usuario elimina, desde Identity, el vínculo entre su identidad de Block-Auth y su cuenta en tu app.	Borra el vínculo de `externalId`. El próximo login con Block-Auth pedirá vincular de nuevo.

Cuando tu backend desvincula una cuenta con /api/auth/link/revoke, no se envía webhook: ya lo sabes.

La petición

Un POST con un cuerpo JSON y dos cabeceras:

Cabecera	Valor
`X-BlockAuth-Timestamp`	Momento del envío, en segundos Unix.
`X-BlockAuth-Signature`	`v1=` seguido de la firma en hexadecimal.

Cuerpo

{
  "event": "signout",
  "address": "0x7f85…46d8",
  "externalId": "user-1234",
  "sessionId": "8f1c…",
  "reason": "signed_out",
  "apiKey": "your_api_key",
  "iat": 1762851600,
  "jti": "3b9e0f4c2a…"
}

address va siempre en minúsculas.
externalId es tu propio ID de usuario si está vinculado, o null.
sessionId es null cuando el cierre de sesión viene de tu propia llamada a /api/auth/signout.
jti es único en cada petición: úsalo para ignorar una petición que ya hayas procesado.

Verifica la firma

No te fíes nunca de un webhook sin verificar. La firma es un HMAC-SHA256 de timestamp.body (la cabecera del timestamp, un punto y el cuerpo en bruto), con el hash SHA-256 de tu apiSecret como clave.

Lee el cuerpo en bruto, antes de interpretar el JSON.
Recházalo si el timestamp se aleja más de 5 minutos de tu reloj.
Calcula la firma y compárala con X-BlockAuth-Signature en tiempo constante.
Comprueba que apiKey es la tuya.

Con las rutas del paquete de Block-Auth no escribes nada de esto: POST /webhook hace los cuatro pasos, y sus opciones isReplay e isRevoked se encargan de los envíos repetidos y de cerrar sesiones. Si escribes la ruta tú mismo, verifyWebhook de AuthCodeClient hace los pasos 1 a 3 en todos los lenguajes. El SDK de .NET también comprueba apiKey; en Node.js, PHP y Python, compruébala tú:

Cómo lo integras

const event = blockauth.verifyWebhook(
  req.body,
  req.get('X-BlockAuth-Timestamp'),
  req.get('X-BlockAuth-Signature'),
)
if (event.apiKey !== process.env.BLOCKAUTH_API_KEY) return res.status(400).end()

El endpoint completo para cada lenguaje está en las guías: React, Vue, Angular y PHP, Python, .NET, Node.js.

Entrega

Block-Auth envía cada evento una sola vez. No hay reintentos.
Tu endpoint tiene 5 segundos para responder. Las redirecciones no se siguen.
Responde 2xx en cuanto la firma sea válida y haz el trabajo después.

Como un webhook puede perderse si tu servidor está caído, no dependas solo de él: tu sesión también debe terminar en signedExpiredAt.