Cuando un cliente paga, alguien tiene que avisar a tu sistema: marcar el pedido como pagado, preparar el stock, emitir la factura y enviar la confirmación. Hacerlo revisando el extracto funciona al principio, pero frena la operación cuando las ventas crecen. Para eso existen los webhooks de pago.
Qué es un webhook de pago
Es una notificación automática que la plataforma de pagos envía a una dirección (URL) de tu sistema cada vez que ocurre algo con un cobro: se pagó un Pix, se compensó un boleto, se aprobó o se reembolsó una compra con tarjeta. En lugar de que tu sistema pregunte cada cierto tiempo si el cliente ya pagó, recibe el aviso en cuanto cambia el estado.
Cómo funciona, paso a paso
- Indicas la URL: la dirección de tu sistema que recibirá los avisos, configurada en el panel o enviada en el campo postbackUrl del cobro creado por la API.
- El cliente paga: con Pix, tarjeta de crédito o boleto.
- La plataforma envía el aviso: una petición HTTP POST con los datos del evento en JSON.
- Tu sistema confirma el pedido: revisa el aviso, actualiza el estado y responde con HTTP 200 para indicar que lo recibió.
Qué contiene un webhook
Cada aviso incluye un identificador único del evento, el estado del pago y los datos de la transacción. Un ejemplo simplificado: {"id": "evt_...", "status": "LIQUIDATED", "data": {"value": "16.5", "txId": "...", "method": "pix"}}.
En Sila Pay también eliges en el panel qué eventos quieres recibir, como compra aprobada (purchase_approved), Pix pagado (pix_paid), boleto pagado (boleto_paid), Pix caducado y compra reembolsada.
Dónde ayudan los webhooks en el día a día
- Actualización automática de pedidos: el pedido pasa a "pagado" en tu sistema o ERP sin que nadie revise extractos.
- Stock y envíos: la preparación empieza en cuanto se confirma el pago.
- Productos digitales y servicios: libera accesos, entradas o reservas justo después del pago.
- Cobros caducados: entérate de cuándo un Pix o un boleto venció sin pago y retoma el contacto.
¿Quieres automatizar la confirmación de tus pedidos? Crea tu cuenta en Sila Pay
Buenas prácticas para recibir webhooks
- Valida la firma: cada aviso de Sila Pay trae el header X-Silapay-Signature, un HMAC-SHA256 calculado con tu secret. Compruébalo antes de procesar.
- Responde rápido: devuelve HTTP 200 en un máximo de 5 segundos y deja para después las tareas lentas, como emitir la factura.
- Gestiona los duplicados: si tu sistema no responde, la plataforma vuelve a intentarlo; usa el id del evento para no procesar el mismo aviso dos veces.
- Usa HTTPS y protege el secret: guárdalo en el servidor, nunca en la web ni en la app.
Preguntas frecuentes
¿Necesito ser programador para usar webhooks?
Alguien tiene que preparar la dirección que recibe los avisos. Muchos ERP y plataformas de tienda ya incluyen esta función; si usas WooCommerce o Shopify, Sila Pay tiene plugins para integrar tu tienda.
¿Qué diferencia hay entre un webhook y una API?
Con la API, tu sistema llama a la plataforma, por ejemplo para crear un cobro. Con el webhook, es la plataforma la que llama a tu sistema para avisar de que algo cambió. Los dos suelen trabajar juntos.
¿Y si mi sistema está caído?
Sila Pay hace nuevos intentos automáticos cuando no recibe la respuesta HTTP 200. Aun así, conviene mantener una rutina de conciliación para caídas más largas.
¿Dónde encuentro la documentación?
En doc.silapay.pro, con la lista de eventos, el formato del payload y un ejemplo de verificación de la firma.
Confirma pedidos automáticamente, sin revisar extractos. Regístrate en Sila Pay