Ganchos Web > Introducción

Usa webhooks cuando tu sistema deba enterarse de los pagos y mensajes en el momento en que ocurren, en lugar de consultar a Hyfin una y otra vez.

Los webhooks permiten que Hyfin avise a tu sistema de los cambios en cuanto ocurren, para que no tengas que estar consultando constantemente. Una vez que los actives, Hyfin envía un mensaje a tu URL en cuanto ocurre un evento.

habilitando webhooks

Activas los webhooks para un sitio completo o para una orden de compra enviando una URL de webhook al endpoint correspondiente. Este es el JSON que necesita cada endpoint.


Punto Final
Muestra JSON
Agregar/Actualizar Sitio
Al agregar o actualizar un sitio, puedes activar un webhook para todo el sitio. Un webhook de sitio te envía todas las notificaciones de órdenes de compra y pagos de ese sitio.
			
{
  "external_id": "12345678",
  "webhook": {
    "active": true,
    "url": "https://mysoftware.com/webhook"
  }
}


		
Agregar/Actualizar Orden de compra
Al agregar o actualizar una orden de compra, puedes activar un webhook para esa orden de compra. Te envía todas las notificaciones sobre la orden de compra.
			
{
  "external_id": "39772921",
  "webhook_url": "https://mysoftware.com/webhook/{invoice_id}"
}


		

Eventos de Webhook

Cuando se establece una URL de webhook, Hyfin envía los siguientes mensajes.

Acción
Detalle
Pago
Un pago en una orden de compra alcanza un nuevo estado, como capturado, liquidado, anulado, reembolsado o con contracargo. Cada estado se envía una vez por pago.
Notificación
Un mensaje de texto, correo electrónico o mensaje de WhatsApp fue enviado, entregado, leído, retrasado o fallido, o el cliente hizo clic en el enlace de pago.

Reintentos

Su URL de webhook debe responder con un código de estado HTTP exitoso (cualquier 2xx) dentro de 30 segundos. Un estado distinto de 2xx, un tiempo de espera agotado o una conexión que no se pueda establecer se considera una entrega fallida y el mensaje se reenvía según el siguiente calendario.

Intento de reintentar
Reenviado
#1
5 minutos después de la webhook inicial
#2
1 hora después
#3
2 horas después
#4
24 horas después
#5
48 horas después

Hay un máximo de cinco intentos de reenvío. Cada retraso de la tabla se mide a partir del intento anterior y no del webhook inicial, por lo que el quinto y último intento se realiza unos 3.1 días después. Si ese también falla, el mensaje no se vuelve a enviar.

Reglas de entrega

  • La URL del webhook debe usar HTTPS. Una URL que use HTTP nunca recibe entregas y no se reintenta.
  • Se rechaza una URL que apunte a una dirección de red privada, de loopback o reservada. Una solicitud que establezca una se rechaza, y un nombre de host que se resuelva a una no recibe entregas.
  • Las redirecciones no se siguen. Una respuesta 3xx cuenta como una entrega fallida, así que use la dirección final como la URL de su webhook.
  • Cuando 20 webhooks seguidos de un sitio fallan en todos los reintentos, los webhooks de ese sitio se pausan. Mientras estén pausados, los webhooks nuevos no se envían, ni tampoco se envían después. Comuníquese con soporte para reanudarlos una vez que su endpoint esté corregido.