Skip to main content

Webhooks

Los webhooks empujan eventos a tu servidor en el momento en que ocurren: cargos creados y pagados, aprobaciones solicitadas, presupuestos agotados. Cada entrega va firmada con HMAC-SHA256 para que puedas demostrar que vino de Payzor.

1. Registra un endpoint

Desde una sesión de consola:
Respuesta: el secreto de firma se muestra una sola vez:
Un array events vacío significa todos los eventos. Pasa un subconjunto para filtrar, por ejemplo "events": ["payment.succeeded", "budget.exhausted"].

2. Recibe las entregas

Cada POST a tu endpoint incluye: El cuerpo es un sobre JSON; data lleva la carga del evento:

3. Verifica la firma

La firma se calcula sobre los bytes crudos del cuerpo (no sobre el JSON reserializado) así:
donde <t> es la marca de tiempo de la cabecera de firma. Compara con una igualdad resistente a ataques de tiempo.
Verificar contra el cuerpo crudo importa: si primero parseas y vuelves a serializar el JSON, el orden de las claves o el formato de los decimales pueden cambiar y la verificación fallará incluso en llamadas legítimas.
Opcionalmente comprueba también que t esté dentro de unos 5 minutos respecto a ahora (protección contra repetición).

4. Responde rápido, procesa en segundo plano

Devuelve cualquier 2xx cuanto antes. Si tu handler lanza una excepción, Payzor reintenta con backoff exponencial. Las entregas se guardan en memoria por endpoint; puedes revisar las recientes en:

Catálogo de eventos

Cargas completas: Referencia de eventos de webhook.
Trata tus handlers de webhooks como idempotentes. Los reintentos implican que puedes recibir el mismo evento más de una vez: deduplica por event.id.