Webhooks

¿Qué son los Webhooks?

Los webhooks te permiten recibir notificaciones HTTP POST en tiempo real cuando ocurren eventos específicos en tu cuenta de Zynvo. En lugar de hacer polling constantemente a la API, Zynvo enviará automáticamente datos del evento a la URL que configures.

Configuración

Puedes configurar tus webhooks desde el Dashboard de Zynvo en la sección de Configuración > Webhooks. Para cada webhook debes proporcionar:

URL de destino: Endpoint HTTPS que recibirá las notificaciones
Eventos: Selecciona qué eventos quieres recibir
Secret: Se genera automáticamente para validar las solicitudes

Eventos Soportados

Empresas

`enterprise.updated`

Se dispara cuando se actualiza información de una empresa.

{
  "event": "enterprise.updated",
  "timestamp": "2024-03-15T10:30:00Z",
  "data": {
    "rut": "123456789",
    "legal_name": "Empresa Ejemplo S.A.",
    "trade_name": "Ejemplo",
    "status": "READY",
    "changes": {
      "status": {
        "from": "PENDING",
        "to": "READY"
      }
    }
  }
}

Pagos

`payment.created`

Se dispara cuando se crea un nuevo pago.

{
  "event": "payment.created",
  "timestamp": "2024-03-15T10:30:00Z",
  "data": {
    "payment_id": "pay_abc123",
    "enterprise_rut": "123456789",
    "amount": 1500.00,
    "currency": "UYU",
    "status": "pending",
    "redirect_url": "https://payments.zynvo.com/pay/pay_abc123",
    "created_at": "2024-03-15T10:30:00Z"
  }
}

User eFactura

Se dispara cuando finaliza la validación asíncrona de credenciales de DGI. Este evento es el resultado del endpoint de validar credenciales de eFactura.

{
  "event": "efactura.login",
  "timestamp": "2024-03-15T10:30:00Z",
  "data": {
    "enterprise_rut": "123456789",
    "status": "success",
    "login_status": "OK",
    "permissions": ["HOMO", "PROD"],
    "missing_permissions": [],
    "message": "Conexión exitosa con eFactura"
  }
}

Posibles valores de status:

success: Login exitoso
failed: Error en el login
permissions_updated: Cambio en permisos

Posibles valores de permissions:

HOMO: Acceso al ambiente de homologación de DGI
PROD: Acceso al ambiente de producción de DGI

Estructura del Request

Todos los webhooks se envían como HTTP POST en formato JSON:

POST https://tu-servidor.com/webhook
Content-Type: application/json

Reintentos

Si tu endpoint no responde con un status 2xx, Zynvo reintentará la entrega:

Primer reintento: Después de 1 minuto
Segundo reintento: Después de 5 minutos
Tercer reintento: Después de 30 minutos

Después de 3 intentos fallidos, el webhook será marcado como fallido y podrás verlo en el Dashboard.

Mejores Prácticas

Responde rápidamente

Responde con 200 OK inmediatamente y procesa el webhook de forma asíncrona. No hagas que Zynvo espere por operaciones largas.

Usa HTTPS

Tu endpoint debe usar HTTPS. Zynvo no enviará webhooks a URLs HTTP inseguras.

Bienvenida

Recursos

Guías

¿Qué son los Webhooks?

Configuración

Eventos Soportados

Empresas

`enterprise.updated`

Pagos

`payment.created`

User eFactura

Estructura del Request

Reintentos

Mejores Prácticas

​¿Qué son los Webhooks?

​Configuración

​Eventos Soportados

​Empresas

​enterprise.updated

​Pagos

​payment.created

​User eFactura

​efactura.login

​Estructura del Request

​Reintentos

​Mejores Prácticas

¿Qué son los Webhooks?

Configuración

Eventos Soportados

Empresas

`enterprise.updated`

Pagos

`payment.created`

User eFactura

`efactura.login`

Estructura del Request

Reintentos

Mejores Prácticas