En esta página
Descripción general
Conecta Paymos con tu backend mediante endpoints de webhook firmados y aislados por entorno, con un flujo de entrega completo.
Paymos envía un POST por HTTPS cuando una factura, un retiro o un depósito de canal de pago cambian de estado. Los webhooks son la señal asíncrona fiable para tu backend: las respuestas de la API inician una operación, mientras que los eventos de webhook te cuentan qué ocurrió después del procesamiento en la blockchain.
Flujo de integración
- Crea un endpoint de webhook en Panel → Desarrollador → Webhooks.
- Elige una o varias categorías de eventos:
Invoice,Withdrawal,Payment channel. - Si quieres, restringe los eventos de factura y de canal de pago a proyectos concretos: comparten un mismo filtro. Los eventos de retiro abarcan todo el comercio y no lo aplican.
- Guarda en tu servidor el secreto
whsec_…que se muestra. - Verifica cada entrega contra el cuerpo bruto de la petición, sin modificar.
- Persiste
event_id, responde con2xxy procesa el evento de forma asíncrona.
Producción y Sandbox tienen endpoints, secretos y eventos separados. Un evento de Sandbox nunca se entrega a un endpoint de producción.
Reglas de los endpoints
- La URL debe usar HTTPS.
- Se pueden configurar hasta 10 endpoints por comercio y entorno.
- La misma URL activa no puede registrarse dos veces en un mismo entorno.
- Un endpoint debe suscribirse al menos a una categoría.
- Si no hay filtro de proyectos, se incluyen todos los proyectos.
- Suspender o eliminar un endpoint detiene las nuevas entregas hacia él.
Cabeceras de la entrega
| Cabecera | Contrato |
|---|---|
Content-Type |
application/json; charset=utf-8 |
X-Webhook-Id |
Identificador estable evt_…; no cambia entre reintentos ni en un reenvío manual |
X-Webhook-Timestamp |
Segundos Unix de este intento de entrega |
X-Webhook-Signature |
t={timestamp},v1={hmac_hex}; puede llevar dos valores v1 durante una rotación |
La entrega es al menos una vez y el orden no está garantizado. Deduplica por X-Webhook-Id y aplica después el estado del recurso que viene en data, en lugar de contar eventos o dar por hecho un orden de llegada.
Documentación de webhooks
- Catálogo de eventos — todos los tipos de evento de facturas, retiros y canales de pago
- Contrato del contenido — el sobre y las instantáneas de recurso
- Verificar firmas — verificación HMAC sobre el cuerpo bruto y rotación del secreto
- Entrega y reintentos — tiempo límite, backoff, idempotencia y reenvío
- Probar webhooks — requisitos en Sandbox y consola interactiva