Webhooks
Recibe cambios verificados sin depender de que el cliente vuelva a tu sitio.
Registrar un endpoint
{
"url": "https://example.com/api/webhooks/billete",
"events": ["checkout.completed", "subscription.renewed", "payment.failed"]
}Guarda el secreto de firma en tu servidor. Suscribe solo los eventos que necesitas; ["*"] selecciona todos. Los eventos llegan con la forma de la versión del endpoint (apiVersion): por defecto, la de la petición que lo crea.
| Método | Ruta | Acción |
|---|---|---|
| POST / GET | /v1/webhook-endpoints | Crear / listar |
| GET / PATCH / DELETE | /v1/webhook-endpoints/:endpoint | Consultar / actualizar / eliminar |
Eliminar un endpoint deja de enviarle eventos y responde el endpoint con deletedAt; sus entregas se conservan y se siguen viendo en el dashboard.
Verificar una entrega
Billete usa Standard Webhooks: webhook-id, webhook-timestamp y webhook-signature. Verifica la firma con el cuerpo original, antes de transformarlo. El verificador del SDK admite Web Crypto y evita implementar criptografía propia.
Procesar con seguridad
- Verifica la firma y la antigüedad.
- Comprueba el entorno esperado.
- Registra
event.idcon una restricción única en tu almacenamiento. - Guarda el evento y el trabajo pendiente de forma atómica.
- Devuelve un código 2xx después de guardar de forma duradera lo necesario.
Si tu servidor no responde 2xx, Billete reintenta durante unas 41 horas, cada vez más espaciado. En el dashboard (Desarrolladores → Webhooks) ves cada entrega de un endpoint con su último código y respuesta, la reenvías, le mandas un evento de prueba (webhook_endpoint.test) y rotas su secreto: el nuevo firma desde el siguiente intento y el anterior deja de servir en ese momento.
Las entregas pueden repetirse. No dependas de su orden: si necesitas el estado actual, consulta el recurso. No marques un evento como procesado antes de asegurar su efecto o el trabajo que lo ejecutará.