Eventos

Un evento registra que un recurso de tu cuenta llegó a un estado, por ejemplo que una factura quedó cancelada. Es el mismo sobre que Fiscalapi firma y entrega a tus webhooks. Con estos endpoints consultas los eventos de los últimos 30 días, los reenvías a un webhook y disparas eventos de prueba.

Revisa la introducción a los webhooks para conocer los tipos de evento, la forma del sobre y cómo conciliar eventos después de una caída de tu receptor.

Los endpoints de eventos requieren el permiso Webhooks.Manage y responden los errores con las mismas reglas que los de webhooks. El sobre de cada evento viene siempre en UTC con Z final, sin importar el header X-TIME-ZONE.

GET/api/v4/events

Listar eventos

Este endpoint devuelve los eventos de tu cuenta de los últimos 30 días, del más nuevo al más viejo. Cada elemento es el sobre tal como se entregó, con createdAt en UTC sin importar el header X-TIME-ZONE.

Query parameters

  • Name
    type
    Type
    string?
    Description

    Solo los eventos de este tipo. Acepta también webhook.test.

  • Name
    relatedObjectId
    Type
    string?
    Description

    Solo los eventos de este recurso, por ejemplo una factura.

  • Name
    from
    Type
    string?
    Description

    Instante UTC inicial, incluido, en ISO 8601.

  • Name
    to
    Type
    string?
    Description

    Instante UTC final, incluido. Omitido, es ahora. El rango dura como máximo 30 días.

  • Name
    pageNumber
    Type
    int?
    Description

    Número de página.

    Default:
    1
  • Name
    pageSize
    Type
    int?
    Description

    Eventos por página, de 1 a 50.

    Default:
    10

Errores

Las fallas llegan en data como ValidationFailure, con el parámetro que las causó. En el mensaje del tipo, <tipo> es el tipo enviado.

EstadoCuándo ocurreMensaje
400El tipo de evento no existe. Llega como falla de validación en Type.El tipo de evento '<tipo>' no existe.
400El inicio del rango es posterior al fin. Llega como falla de validación en From.'from' no puede ser posterior a 'to'.
400El rango pasa de 30 días. Llega como falla de validación en From.El rango de fechas no puede exceder 30 días.
400pageSize está fuera de 1 a 50. Llega como falla de validación en pageSize.'pageSize' debe estar entre 1 y 50.
400pageNumber está fuera de rango. Llega como falla de validación en pageNumber.'pageNumber' debe estar entre 1 y 42949672.

Request

GET
/api/v4/events?type=invoice.canceled&from=2026-10-01T00:00:00Z
curl --location 'https://test.fiscalapi.com/api/v4/events?type=invoice.canceled&from=2026-10-01T00:00:00Z&pageNumber=1&pageSize=10' \
--header 'X-TENANT-KEY: <tenant_key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>'

Response

{
    "data": {
        "items": [
            {
                "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
                "type": "invoice.canceled",
                "createdAt": "2026-10-12T18:47:53Z",
                "personId": "4f6a2c1e-8b3d-4e5f-9a7b-1c2d3e4f5a6b",
                "data": {
                    "relatedObject": {
                        "id": "0b6c1f2e-7d8a-4b9c-8e1f-2a3b4c5d6e7f",
                        "type": "invoice",
                        "url": "/api/v4/invoices/0b6c1f2e-7d8a-4b9c-8e1f-2a3b4c5d6e7f"
                    },
                    "status": "X",
                    "previousStatus": "C"
                }
            }
        ],
        "pageNumber": 1,
        "totalPages": 1,
        "totalCount": 1,
        "hasPreviousPage": false,
        "hasNextPage": false
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}
GET/api/v4/events/<id>

Obtener evento

Este endpoint devuelve el sobre exacto de un evento, el mismo que se firmó y se entregó. El id es el webhook-id de la entrega.

Errores

EstadoCuándo ocurreMensaje
404El evento no existe en tu cuenta o tiene más de 30 días. Llega en details.No such resource for the given Id: <id>

Request

GET
/api/v4/events/<id>
curl --location 'https://test.fiscalapi.com/api/v4/events/7c9e6679-7425-40de-944b-e07fc1f90ae7' \
--header 'X-TENANT-KEY: <tenant_key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>'

Response

{
    "data": {
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "type": "invoice.canceled",
        "createdAt": "2026-10-12T18:47:53Z",
        "personId": "4f6a2c1e-8b3d-4e5f-9a7b-1c2d3e4f5a6b",
        "data": {
            "relatedObject": {
                "id": "0b6c1f2e-7d8a-4b9c-8e1f-2a3b4c5d6e7f",
                "type": "invoice",
                "url": "/api/v4/invoices/0b6c1f2e-7d8a-4b9c-8e1f-2a3b4c5d6e7f"
            },
            "status": "X",
            "previousStatus": "C"
        }
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}
POST/api/v4/events/<id>/resend

Reenviar evento

Este endpoint crea una entrega nueva del evento al webhook que indicas, firmada y de un solo intento, sin reintentos. Responde 202; sigue el resultado en Listar entregas. El reenvío no filtra por los tipos ni las personas del webhook: es una petición explícita.

Un reenvío que falla no genera el correo de reintentos agotados, pero un 410 sí deshabilita el webhook. El 2xx de un evento real cuenta como respuesta exitosa del webhook; el de un evento de prueba, no.

Modelo

  • Name
    webhookId
    Type
    string?
    Description

    Id del webhook que recibe el evento. Envíalo siempre para reenviar a un webhook de URL: omitido, el evento va a la escucha de fiscalapi listen de la persona autenticada, que sirve para probar en local.

Respuesta

  • Name
    deliveryId
    Type
    string?
    Description

    Id de la entrega nueva.

  • Name
    webhookId
    Type
    string?
    Description

    Id del webhook que la recibe.

Errores

EstadoCuándo ocurreMensaje
400Enviaste webhookId vacío. Llega como falla de validación en WebhookId.'Webhook Id' no debería estar vacío.
400Enviaste un campo que el modelo no tiene. Llega como falla de validación en $.<campo>.El campo '<campo>' no existe en este recurso.
400El webhook está deshabilitado. Llega en details.El webhook está deshabilitado: habilítalo antes de reenviarle eventos.
404El evento no existe en tu cuenta o tiene más de 30 días, o el webhook no existe en tu cuenta. Llega en details.No such resource for the given Id: <id>
409El destino es una escucha de fiscalapi listen que no está conectada, por ejemplo si omitiste webhookId y no tienes una escucha abierta. Llega en details.La escucha de CLI no está conectada; ejecuta fiscalapi listen.
429Excediste el límite de solicitudes de tu API key. Llega en message, con el detalle en details y el header Retry-After. Ver Límite de solicitudes.Too Many Requests

Request

POST
/api/v4/events/<id>/resend
curl --location 'https://test.fiscalapi.com/api/v4/events/7c9e6679-7425-40de-944b-e07fc1f90ae7/resend' \
--header 'X-TENANT-KEY: <tenant_key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api_key>' \
--data-raw '{
  "webhookId": "6f7a8b9c-0d1e-4f2a-b3c4-d5e6f7a8b9c0"
}'

Response

{
    "data": {
        "deliveryId": "d3e4f5a6-b7c8-4d9e-8f0a-1b2c3d4e5f6a",
        "webhookId": "6f7a8b9c-0d1e-4f2a-b3c4-d5e6f7a8b9c0"
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 202
}
POST/api/v4/events/trigger

Disparar evento de prueba

Este endpoint genera un evento del tipo que indicas, con la forma de uno real de su tipo, y lo entrega solo al webhook que indicas o, si lo omites, a tu escucha de fiscalapi listen. Es el endpoint que usa fiscalapi trigger y solo funciona en el ambiente de pruebas. Responde 202 con los ids del evento y del webhook; sigue el resultado en Obtener evento y en Listar entregas.

Como el reenvío, no filtra por los tipos ni las personas del webhook. La entrega es una prueba de un solo intento, sin reintentos, y su 2xx no cuenta para la salud del webhook; ver Probar tu receptor. Los demás webhooks de tu cuenta no reciben el evento.

Modelo

  • Name
    type
    Type
    string
    required
    Description

    Tipo de evento. Acepta cualquier tipo de evento salvo webhook.test.

  • Name
    relatedObjectId
    Type
    string?
    Description

    Id de un recurso de tu cuenta, de hasta 36 caracteres, que viaja en data.relatedObject.id. Omitido, el evento lleva un id sintético y el GET de relatedObject.url responde 404.

  • Name
    personId
    Type
    string?
    Description

    Persona de tu cuenta dueña del recurso, que viaja en personId. Omitido, el evento va sin persona.

  • Name
    webhookId
    Type
    string?
    Description

    Id del webhook que recibe el evento. Omitido, el evento va a la escucha de fiscalapi listen de la persona autenticada.

Respuesta

  • Name
    eventId
    Type
    string?
    Description

    Id del evento disparado.

  • Name
    webhookId
    Type
    string?
    Description

    Id del webhook que lo recibe.

Errores

Una falla de validación llega en data como ValidationFailure, con el campo que la causó; las demás llegan con el mensaje en details. En el mensaje del tipo, <tipo> es el tipo enviado, vacío si lo omitiste.

EstadoCuándo ocurreMensaje
400La petición no trae cuerpo. Llega como falla de validación en $.El cuerpo de la petición es requerido y no debe estar vacío.
400Falta type, el tipo no existe o es webhook.test. Llega como falla de validación en Type.El tipo de evento '<tipo>' no existe.
400Enviaste relatedObjectId vacío. Llega como falla de validación en RelatedObjectId.'Related Object Id' no debería estar vacío.
400relatedObjectId pasa de 36 caracteres. Llega como falla de validación en RelatedObjectId.'Related Object Id' debe ser menor o igual que 36 caracteres. Ingresó <n> caracteres.
400Enviaste webhookId vacío. Llega como falla de validación en WebhookId.'Webhook Id' no debería estar vacío.
400Enviaste un campo que el modelo no tiene. Llega como falla de validación en $.<campo>.El campo '<campo>' no existe en este recurso.
400La persona no es de tu cuenta. Llega en details.La persona especificada no es válida o no pertenece a tu organización.
400El webhook está deshabilitado. Llega en details.El webhook está deshabilitado: habilítalo antes de probarlo.
403Llamas en producción. Llega en details.fiscalapi trigger no está disponible en producción; usa el ambiente de pruebas.
404El webhook no existe en tu cuenta. Llega en details.No such resource for the given Id: <id>
409El destino es una escucha de fiscalapi listen que no está conectada, por ejemplo si omitiste webhookId y no tienes una escucha abierta. Llega en details.La escucha de CLI no está conectada; ejecuta fiscalapi listen.
429Excediste el límite de solicitudes de tu API key. Llega en message, con el detalle en details y el header Retry-After. Ver Límite de solicitudes.Too Many Requests

Request

POST
/api/v4/events/trigger
curl --location 'https://test.fiscalapi.com/api/v4/events/trigger' \
--header 'X-TENANT-KEY: <tenant_key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api_key>' \
--data-raw '{
  "type": "invoice.canceled",
  "relatedObjectId": "0b6c1f2e-7d8a-4b9c-8e1f-2a3b4c5d6e7f",
  "personId": "4f6a2c1e-8b3d-4e5f-9a7b-1c2d3e4f5a6b",
  "webhookId": "6f7a8b9c-0d1e-4f2a-b3c4-d5e6f7a8b9c0"
}'

Response

{
    "data": {
        "eventId": "3f9c1d2e-7b4a-4e8f-9a1b-2c3d4e5f6a7b",
        "webhookId": "6f7a8b9c-0d1e-4f2a-b3c4-d5e6f7a8b9c0"
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 202
}

¿Le resultó útil esta página?