Probar webhooks

Probar webhooks en el sandbox

La actividad del sandbox dispara webhooks igual que la de producción, hacia los endpoints registrados en la organización sandbox, y siempre con livemode: false.

Es la forma de verificar tu handler entero —la firma, el parseo, tu lógica— antes de que un cliente real pague.

1. Registra tu endpoint en el sandbox

Enciende el modo sandbox y ve a Desarrolladores → Webhooks. Los webhooks que crees ahí pertenecen al sandbox: no reciben nada de producción, y los de producción no reciben nada del sandbox.

Ponle un secret: es la clave con la que se firma cada entrega.

Para desarrollar en tu máquina necesitas una URL pública. Cualquier túnel sirve, o un servicio como webhook.site si solo quieres mirar el cuerpo y los headers.

2. Dispara un evento de prueba

En la fila del webhook, el botón "Enviar evento de prueba" manda un evento de ejemplo del tipo que elijas.

El evento de prueba viaja por el mismo camino que un evento real: mismos headers, misma firma, mismo tiempo límite y queda registrado en el mismo historial. Lo que ves en la prueba es lo que va a pasar de verdad.

Dos diferencias, las dos a propósito:

	Evento real	Evento de prueba
Reintentos	Hasta 3 intentos, cada 5 minutos	Un solo intento
Datos	Los de tu cobro	Nombres, montos e ids obviamente de ejemplo

Un evento de prueba no se reintenta porque estás depurando tu endpoint: no tiene sentido esperar 10 minutos por reintentos de algo que ya sabes que falló. Corrige y vuelve a disparar.

El selector solo ofrece los tipos a los que ese webhook está suscrito. Si eliges uno que no está en su lista, la llamada se rechaza diciéndotelo, en vez de entregar algo que en producción nunca llegaría.

3. Verifica la firma

Cada entrega firmada trae el header X-Webhook-Signature:

X-Webhook-Signature: t=1789415801,v1=b03900efcfc5b467a9192c1e448a82bd77187fb70cda36cefffc810d7564170c

v1 es el HMAC-SHA256 de <t>.<cuerpo crudo> con el secret de ese webhook. La función de verificación completa, lista para copiar, está en Verificar la firma.

Durante la ventana de deprecación las entregas llevan también el header antiguo X-Webhook-Secret, con el secreto en texto plano. No escribas integraciones nuevas contra ese header; se va a dejar de enviar.

4. Revisa el historial de entregas

El botón del reloj, en la fila del webhook, abre el historial: cada intento de entrega de los últimos 30 días, del más reciente al más antiguo.

Columna	Qué te dice
Evento	El tipo que se envió
Resultado	Entregado o fallido
Código HTTP	Lo que respondió tu servidor. Vacío cuando no respondió nada
Intento	1, 2 o 3 dentro de la política de reintentos
Prueba	Marca los que disparaste tú desde el panel

Se registran todos los intentos, no solo el que funcionó. Si tu endpoint respondió 500 dos veces y 200 a la tercera, vas a ver las tres filas. Un tiempo agotado se registra sin código HTTP y con el motivo en su lugar.

Ramifica por `livemode`

Todo evento del sandbox trae livemode: false en el cuerpo, incluidos los de prueba:

{
  "eventType": "PAYMENT_SUCCESS_EVENT",
  "livemode": false,
  "client": { "...": "..." },
  "payment": { "...": "..." }
}

Usa ese campo como interruptor. Si tu handler emite facturas, toca tu contabilidad o le escribe al cliente, haz que ignore o marque aparte todo lo que llegue con livemode: false — incluso desde tu propio servidor de producción, por si alguna vez apuntas un endpoint del sandbox a él.

Qué probar

Que tu handler verifica la firma y rechaza un cuerpo alterado.
Que tolera un evento repetido: un reintento puede llegar después de que ya procesaste el primero.
Que responde rápido. Si tardas demasiado, la entrega se cuenta como fallida aunque tu servidor haya hecho el trabajo.
Que no se cae con un tipo de evento que no esperabas.