Todos los webhooks enviados por Bily comparten una estructura base común, esto permite procesar, registrar e identificar cada evento de forma consistente, sin importar el tipo de suceso que lo originó.

Cada notificación enviada a tu endpoint incluye información general del evento, así como un objeto data con el detalle específico correspondiente al tipo de evento recibido.

Estructura general

{
  "token": "event_jhfuoRLMr0la0GUPUN8DoCBZ",
  "token-suc": "suc_JBVABGtU2k27kqhrEekIpTwUex",
  "fecha": "2025-03-09T21:08:36.1084041Z",
  "tipo": "cfdi.validacion",
  "data": {
    "tipo": "validacion",
    "objeto": {
    }
}

Atributos del evento

Atributos del evento	Tipo de dato	Descripción
`token`	string	Identificador único del evento. Puede utilizarse para trazabilidad o auditoría
`token-suc`	string	Token de la sucursal relacionada con el evento
`fecha`	string	Fecha y hora en que el evento fue generado, formato ISO 8601
`tipo`	string	Especifica el tipo de evento emitido por Bily.
`data`	string	Contiene la información del evento.
`data.tipo`	string	Especifica el tipo de objeto y determina la estructura y significado del contenido del atributo `objeto`
`data.objeto`	object	Contiene la información específica del evento. Su estructura depende del valor del atributo `data.tipo`

Cómo interpretar el atributo objeto

El atributo data.objeto no tiene una estructura fija para todos los eventos, su contenido cambia dependiendo del valor de data.tipo.

En otras palabras, el campo data.tipo indica qué clase de información contiene data.objeto y cómo debe interpretarse.

Ejemplos:

Si el tipo de evento es cfdi.validacion y data.tipo es validacion, el atributo data.objeto contendrá un objeto del tipo validacion con información detallada sobre el resultado de la validación de un comprobante.

Si el tipo de evento es cfdi.recibido y data.tipo es cfdi, el atributo data.objeto contendrá un objeto del tipo cfdi con información detallada sobre el comprobante recibido.

Si el tipo de evento es cfdi.monitoreo y data.tipo es consulta-estatus-sat, el atributo data.objeto contendrá un objeto del tipo consulta-estatus-sat con información detallada sobre el la consulta de estatus del comprobante.

Recomendación de procesamiento

Al recibir un evento dentro del webhook, se recomienda seguir este flujo:

Leer el valor de tipo
Identificar la estructura esperada de data
Procesar el contenido según el tipo de evento recibido
Registrar el token para control y trazabilidad
Utilizar la información del evento para automatización de procesos

¿Qué sigue?

Consulta la guía Tipos de eventos para conocer a detalle los diferentes tipos de eventos que notifica Bily y la información que estos contienen.