Webhooks y Eventos

"¿Quieres enterarte en tiempo real cuando ocurre algo importante con tus CFDI?"

"¿Necesitas que tu sistema reaccione automáticamente ante cambios fiscales?"

"¿Buscas eliminar procesos manuales y conciliaciones tardías?"

En una operación fiscal moderna, esperar reportes o ejecutar procesos periódicos ya no es suficiente.
Las decisiones deben tomarse en el momento exacto en el que ocurre un evento relevante.

Bily incorpora un modelo de arquitectura orientada a eventos, permitiéndote integrar tus sistemas en tiempo real mediante Webhooks, sin necesidad de consultar constantemente la plataforma.

¿Qué es un evento?

Un evento representa una acción, cambio o detección relevante que ocurre dentro de la plataforma Bily.

Los eventos son generados internamente por Bily y representan hechos como:

La emisión de un CFDI
La recepción de un CFDI
Un cambio de estatus fiscal
El cumplimiento o incumplimiento de una política
La detección de una posible duplicidad
La detección de un proveedor en listas negras
La facturación de un ticket de venta o la emisión de una factura global
El resultado de validación de un CFDI emitido/recibido

¿Qué es un webhook?

Un webhook es un endpoint HTTP configurado por el usuario para recibir notificaciones cuando Bily emite determinados eventos.

¿Cómo funciona la integración basada en eventos?

El flujo de funcionamiento es el siguiente:

Ocurre una acción relevante dentro de Bily
Bily emite un evento
Bily identifica los webhooks configurados que están suscritos a ese evento
Bily notifica a cada webhook enviando la información del evento
Tu sistema recibe el evento y ejecuta la lógica correspondiente

Este modelo permite construir integraciones reactivas, confiables y desacopladas.

¿Qué eventos emite Bily?

Actualmente, Bily emite eventos para los siguientes escenarios:

La recepción de un CFDI
La emisión de un CFDI
La correcta o incorrecta validación de un CFDI
El cumplimiento o incumplimiento de alguna política configurada
La detección de un proveedor en las listas negras del SAT
El cambio de estatus en un CFDI (En proceso de cancelación, Rechazado, Cancelado...)
La detección de una posible duplicidad de CFDI
La facturación de un ticket de venta
La emisión automática de una venta global (PUBLICO EN GENERAL)

Cada evento incluye información estructurada que permite a tus sistemas reaccionar automáticamente.

Casos de uso comunes

El uso de eventos y webhooks permite escenarios como:

Actualizar automáticamente el estatus de un CFDI en tu ERP/POS/CRM
Tomar acción cuando un proveedor entra en listas negras del SAT
Disparar notificaciones internas o externas al personal correspondiente
Ejecutar flujos automáticos de aprobación o revisión
Registrar evidencia para auditoría fiscal
Sincronizar información entre sistemas
Activar procesos administrativos o contables en tiempo real

Configuración de Webhooks

Los webhooks se configuran desde el Panel de Bily.

Cada webhook requiere:

Una URL pública accesible vía HTTPS
Un tipo de autenticación
La selección de los eventos que deseas escuchar

Puedes configurar uno o múltiples webhooks, incluso escuchando los mismos eventos en distintos endpoints.

Consulta el Manual de operación Integración - Webhooks

Tipos de autenticación soportados

Bily soporta múltiples esquemas de autenticación para adaptarse a la seguridad de tu infraestructura:

Sin autenticación

No se requiere autenticación
Ideal para entornos controlados o pruebas

Autenticación básica

Usuario y contraseña
Se envían mediante el encabezado Authorization: Basic ...

Bearer Token

Token enviado en el encabezado:

Authorization: Bearer {token}

Header API Key

Clave enviada en un header configurado
Ejemplo:

X-API-KEY: your_api_key

Buenas prácticas recomendadas

Implementa idempotencia en tus endpoints
Responde siempre con códigos HTTP 200
Registra los eventos recibidos para auditoría y trazabilidad
Valida encabezados y autenticación
Mantén tiempos de respuesta cortos
Maneja reintentos de forma segura

¿Dónde se relaciona con el resto de Bily?

Los eventos se generan como resultado de:

Integraciones de Timbrado
Sincronización SAT
Carga directa de CFDI
Funcionalidad de Control Fiscal Integrado
Políticas y cumplimiento
Facturación automática (Portal de tickets y factura global)
Clasificación y flujos de trabajo
Emisión y recepción de CFDI

Esto permite una integración completa y circular entre Bily y tus sistemas, además Bily cuenta con una bitácora de registros, para consulta y administración de eventos a la cual puedes acceder desde tu Panel (Dashboard).

Consulta el Manual de operación Integración - Webhooks para crear tu primer webhook.

Recomendación final

Si tu operación requiere:

Automatización
Integraciones en tiempo real
Prevención de riesgos fiscales
Eliminación de procesos manuales

El uso de Eventos y Webhooks es altamente recomendado como parte de tu arquitectura de integración.

¿Qué sigue?

Consulta la guía Estructura del evento para conocer a detalle la información que contienen los eventos.