Procesa los webhooks de Security Deposits API a partir del registro actual de la garantía. Verifica la firma y consulta el estado cuando un mensaje pueda estar desactualizado o incompleto. Una captura parcial de Stripe puede ser definitiva: el resto deja de estar disponible.
Esta guía añade una tabla de estados para software de alquiler a la introducción a la API.
¿Cómo verificar un webhook de garantía?
La referencia PayRequest define `X-PayRequest-Signature` como `sha256=` seguido del resumen HMAC-SHA256 del cuerpo original. Usa el secreto configurado, verifica los bytes originales antes de procesar JSON y compara firmas con un método apropiado de tiempo constante. `X-PayRequest-Event` contiene el nombre del evento.
No copies encabezados ni reglas de marcas temporales de Stripe. La página pública no establece orden de entrega, esquema de identificador de evento ni ventana de repetición.
Relaciona eventos con decisiones de reserva
Un webhook informa del estado, pero no demuestra daños. Conserva acuerdo, inspección y decisión en tu sistema.
| Evento o estado | Significado | Acción |
|---|---|---|
| deposit.created / pending | Solicitud sin retención confirmada | Esperar autorización |
| deposit.authorized | Fondos anteriormente retenidos | Revisar estado y capture_before |
| deposit.captured | Cobro completado | Registrar importe y estado final |
| deposit.partially_captured | Resultado según proveedor | Consultar registro actual |
| deposit.released | Retención liberada | No llamarlo reembolso |
| deposit.expired | Retención confirmada vencida | Revisar obligaciones pendientes |
| deposit.failed | Operación fallida | Revisar registro y contexto |
¿Por qué una captura parcial Stripe emite deposit.captured?
PayRequest documenta una única captura final para Stripe. Una autorización de €350 con cobro de €150 libera €200. El estado es `captured`, captured_amount es 150.00 y el evento es `deposit.captured`. La diferencia no es una garantía reutilizable. Consulta Stripe y la guía de captura parcial.
¿Cómo tratar mensajes repetidos o tardíos?
Una notificación repetida no debe generar otro mensaje ni otro cobro. Usa un identificador de entrega solo si el contrato lo documenta; no inventes campos. Consulta el registro actual ante dudas. Una autorización antigua no debe revertir localmente una captura final.
Stripe describe duplicados y eventos desordenados, pero eso no define el calendario de PayRequest. Pending con metadatos de un intento vencido no equivale a expired para una retención anteriormente confirmada.
Relaciona garantías con reservas, separa el alquiler mediante enlaces de pago y revisa límites y la lista de pruebas.
Nota editorial: texto e imagen asistidos por IA. Documentación revisada el 13 de octubre de 2026; no se probaron entregas webhook ni capturas reales.
