Saltar al contenido principal

Webhooks

Esta sección describe cómo utilizar los webhooks de Lummy Invoicing Service para recibir notificaciones en tiempo real sobre eventos importantes.

Eventos Soportados​

Actualmente, los siguientes eventos son soportados por nuestros webhooks:

  • invoice.stamped: Se dispara cuando una factura ha sido exitosamente timbrada por el PAC.
  • invoice.cancelled: Se dispara cuando una factura ha sido exitosamente cancelada.
  • payment.received: Se dispara cuando se registra un pago para un CFDI de Recepción de Pagos.

Configuración de Webhooks​

Para configurar un webhook, debe proporcionar una URL de callback en la configuración de su organización. Cuando ocurra un evento soportado, enviaremos una petición POST a esta URL con un payload JSON que contiene los detalles del evento.

Formato del Payload​

El payload JSON enviado a su URL de callback tendrá la siguiente estructura general:

{
  "eventId": "uuid-del-evento",
  "eventType": "invoice.stamped",
  "timestamp": "2025-01-15T12:30:00Z",
  "data": {
    // Contenido específico del evento
    "invoiceId": "uuid-de-la-factura",
    "cfdiUuid": "uuid-del-cfdi",
    "status": "STAMPED",
    "total": 100.00,
    "currency": "MXN"
  }
}

Ejemplo de invoice.stamped​

{
  "eventId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "eventType": "invoice.stamped",
  "timestamp": "2025-01-15T12:30:00Z",
  "data": {
    "invoiceId": "f3a3b1e0-0b7a-4b1a-9b0a-0a0b0c0d0e0f",
    "cfdiUuid": "40304030-0000-0000-0000-000000000000",
    "status": "STAMPED",
    "total": 100.00,
    "currency": "MXN",
    "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?>..."
  }
}

Seguridad​

Para verificar la autenticidad de los webhooks, cada petición incluirá una firma en la cabecera X-Lummy-Signature. Esta firma se genera utilizando un secreto compartido y el cuerpo de la petición. Deberá verificar esta firma en su servidor para asegurarse de que la petición proviene de Lummy Invoicing Service.

Reintentos​

En caso de que su servidor no responda con un código 2xx (éxito), reintentaremos la entrega del webhook varias veces con un backoff exponencial. Si después de varios intentos la entrega sigue fallando, el webhook será marcado como fallido.

Consideraciones Adicionales​

  • Asegúrese de que su URL de callback sea accesible públicamente y pueda manejar peticiones POST.
  • Responda a las peticiones de webhook lo más rápido posible para evitar timeouts. Si necesita realizar operaciones de larga duración, hágalo de forma asíncrona.