Events

An event records that a resource in your tenant (the space in Fiscalapi that holds your issuers, recipients, credits, and data) reached a status, for example that an invoice was canceled. It's the same envelope that Fiscalapi signs and delivers to your webhooks. Use these endpoints to retrieve the events from the last 30 days, resend them to a webhook, and trigger test events.

See the introduction to webhooks for the event types, the shape of the envelope, and how to reconcile events after your endpoint goes down.

The event endpoints require the Webhooks.Manage permission and return errors under the same rules as the webhook endpoints. Each event's envelope always comes in UTC with a trailing Z, regardless of the X-TIME-ZONE header.

GET/api/v4/events

List events

This endpoint returns your tenant's events from the last 30 days, newest first. Each item is the envelope exactly as it was delivered, with createdAt in UTC regardless of the X-TIME-ZONE header.

Query parameters

Name
type
Type
string?
Description
Only the events of this type. It also accepts webhook.test.
Name
relatedObjectId
Type
string?
Description
Only the events of this resource, for example an invoice.
Name
from
Type
string?
Description
The start of the range, as a UTC instant in ISO 8601, inclusive.
Name
to
Type
string?
Description
The end of the range, as a UTC instant, inclusive. If omitted, it's now. The range spans 30 days at most.
Name
pageNumber
Type
int?
Description
The page number.
Default:
1
Name
pageSize
Type
int?
Description
Events per page, from 1 to 50.
Default:
10

Errors

The failures arrive in data as a ValidationFailure, with the parameter that caused them. In the event type message, <tipo> is the type you sent.

Status	When it happens	Message
400	The event type doesn't exist. It arrives as a validation failure on Type.	El tipo de evento '<tipo>' no existe.
400	The start of the range is after the end. It arrives as a validation failure on From.	'from' no puede ser posterior a 'to'.
400	The range is longer than 30 days. It arrives as a validation failure on From.	El rango de fechas no puede exceder 30 días.
400	pageSize is outside 1 to 50. It arrives as a validation failure on pageSize.	'pageSize' debe estar entre 1 y 50.
400	pageNumber is out of range. It arrives as a validation failure on 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>

Get an event

This endpoint returns an event's exact envelope, the same one that was signed and delivered. The ID is the delivery's webhook-id.

Errors

Status	When it happens	Message
404	The event doesn't exist in your tenant or is older than 30 days. It arrives in 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

Resend an event

This endpoint creates a new delivery of the event to the webhook you specify, signed and in a single attempt, with no retries. It responds with 202; follow the result in List deliveries. A resend doesn't filter by the webhook's event types or people (person: any individual or legal entity registered in your tenant): it's an explicit request.

A resend that fails doesn't trigger the email sent when a delivery runs out of retries, but a 410 does disable the webhook. The 2xx for a real event counts as a successful response from the webhook; the 2xx for a test event doesn't.

Request body

Name
webhookId
Type
string?
Description
The ID of the webhook that receives the event. To resend to a URL webhook, always send it. If omitted, the event goes to the authenticated person's fiscalapi listen listener, which you use to test locally.

Response

Name
deliveryId
Type
string?
Description
The ID of the new delivery.
Name
webhookId
Type
string?
Description
The ID of the webhook that receives it.

Errors

Status	When it happens	Message
400	You sent an empty webhookId. It arrives as a validation failure on WebhookId.	'Webhook Id' no debería estar vacío.
400	You sent a field the model doesn't have. It arrives as a validation failure on $.<field>.	El campo '<campo>' no existe en este recurso.
400	The webhook is disabled. It arrives in details.	El webhook está deshabilitado: habilítalo antes de reenviarle eventos.
404	The event doesn't exist in your tenant or is older than 30 days, or the webhook doesn't exist in your tenant. It arrives in details.	No such resource for the given Id: <id>
409	The destination is a fiscalapi listen listener that isn't connected, for example if you omitted webhookId and don't have a listener open. It arrives in details.	La escucha de CLI no está conectada; ejecuta fiscalapi listen.
429	You exceeded your API key's rate limit. It arrives in message, with the detail in details and the Retry-After header. See Rate limit.	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

Trigger a test event

This endpoint generates an event of the type you specify, shaped like a real event of that type, and delivers it only to the webhook you specify or, if you omit it, to your fiscalapi listen listener. It's the endpoint that fiscalapi trigger uses, and it only works in the test environment. It responds with 202 and the event and webhook IDs; follow the result in Get an event and in List deliveries.

Like a resend, it doesn't filter by the webhook's event types or people. The delivery is a single-attempt test, with no retries, and its 2xx doesn't count toward the webhook's health; see Test your endpoint. The other webhooks in your tenant don't receive the event.

Request body

Name
type
Type
string
required
Description
The event type. It accepts any event type except webhook.test.
Name
relatedObjectId
Type
string?
Description
The ID of a resource in your tenant, up to 36 characters, that the event carries in data.relatedObject.id. If omitted, the event carries a synthetic ID, and the GET to relatedObject.url responds with 404.
Name
personId
Type
string?
Description
The person in your tenant who owns the resource, which the event carries in personId. If omitted, the event has no person.
Name
webhookId
Type
string?
Description
The ID of the webhook that receives the event. If omitted, the event goes to the authenticated person's fiscalapi listen listener.

Response

Name
eventId
Type
string?
Description
The ID of the triggered event.
Name
webhookId
Type
string?
Description
The ID of the webhook that receives it.

Errors

A validation failure arrives in data as a ValidationFailure, with the field that caused it; the others arrive with the message in details. In the event type message, <tipo> is the type you sent, or empty if you omitted it.

Status	When it happens	Message
400	The request has no body. It arrives as a validation failure on $.	El cuerpo de la petición es requerido y no debe estar vacío.
400	type is missing, the type doesn't exist, or it's webhook.test. It arrives as a validation failure on Type.	El tipo de evento '<tipo>' no existe.
400	You sent an empty relatedObjectId. It arrives as a validation failure on RelatedObjectId.	'Related Object Id' no debería estar vacío.
400	relatedObjectId is longer than 36 characters. It arrives as a validation failure on RelatedObjectId.	'Related Object Id' debe ser menor o igual que 36 caracteres. Ingresó <n> caracteres.
400	You sent an empty webhookId. It arrives as a validation failure on WebhookId.	'Webhook Id' no debería estar vacío.
400	You sent a field the model doesn't have. It arrives as a validation failure on $.<field>.	El campo '<campo>' no existe en este recurso.
400	The person isn't in your tenant. It arrives in details.	La persona especificada no es válida o no pertenece a tu organización.
400	The webhook is disabled. It arrives in details.	El webhook está deshabilitado: habilítalo antes de probarlo.
403	You called it in production. It arrives in details.	fiscalapi trigger no está disponible en producción; usa el ambiente de pruebas.
404	The webhook doesn't exist in your tenant. It arrives in details.	No such resource for the given Id: <id>
409	The destination is a fiscalapi listen listener that isn't connected, for example if you omitted webhookId and don't have a listener open. It arrives in details.	La escucha de CLI no está conectada; ejecuta fiscalapi listen.
429	You exceeded your API key's rate limit. It arrives in message, with the detail in details and the Retry-After header. See Rate limit.	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
}