Webhook de pagos cripto: cómo procesar id y status
Guía del webhook de pagos cripto: recibe el estado final con un POST con id y status, comprueba la cabecera x-api-key y actualiza pedidos con seguridad.
Un webhook de pagos cripto informa a tu backend del estado final de un pago. En Qvard es un POST con el id de tu pedido y el estado, así que la lógica del pedido se actualiza sin consultar la API en bucle.
Qué envía el webhook
Qvard llama a tu URL de webhook con una solicitud POST. El cuerpo contiene el id que enviaste al crear el pago y el estado, por ejemplo paid. La solicitud lleva tu token x-api-key en la cabecera.
Comprueba la cabecera x-api-key
Antes de confiar en el mensaje, compara la cabecera x-api-key con el token de tu cuenta. Rechaza las solicitudes sin ella, para que nadie pueda marcar un pedido como pagado llamando directamente a tu endpoint.
x-api-key: sk_live_…
{ "id": "order_1024", "status": "paid" }Actualiza el pedido por id
Busca el pedido por el id del cuerpo y cambia su estado según el status. Marca el pedido como pagado solo cuando el estado sea paid e ignora los estados que tu sistema no gestiona.
Haz el manejador seguro para repetirse
El mismo webhook puede llegar más de una vez. Guarda el id y el estado ya procesados y no hagas nada si ese evento ya se trató. Responde con un código de éxito cuando el cambio esté guardado.
Responde rápido y encola el trabajo lento
Confirma el webhook en cuanto guardes el pedido. Envía correos, facturas y llamadas al almacén desde un trabajo en segundo plano, para que un paso lento nunca provoque un timeout.
Prueba con una factura de demostración
Crea una factura de demostración, págala en la página alojada y comprueba que tu endpoint recibe el webhook antes de pasar a producción.
FAQ
¿Cuál es la diferencia entre la respuesta de la API y el webhook?
La respuesta de la API confirma que el pago se creó y devuelve un redirectUrl. Solo el webhook informa del estado final del pago.
¿Qué pasa si mi endpoint está caído?
La entrega se reintenta, así que tu manejador debe ser seguro para repetirse. Revisa tus registros con regularidad y concilia los pedidos que siguen pendientes.
¿Puedo confiar en un webhook sin x-api-key?
No. Comprueba siempre la cabecera x-api-key antes de cambiar un pedido.
¿Qué estados debo gestionar?
Gestiona paid para los pagos correctos y trata cualquier otro estado como información. La documentación de la API recoge el conjunto completo de valores.
