Webhooks

Webhooks notify your system as an invoice moves through cancellation or when a bulk download (the SAT service that delivers the CFDIs a taxpayer issued and received) changes, so you don't have to poll the API every few minutes. You register an https URL, choose the event types, and Fiscalapi sends it a signed POST each time one occurs.

How it works

1. You register a webhook: the URL that receives the events, the types it subscribes to, and, optionally, the people (person: any individual or legal entity registered in your tenant) whose events it receives. You save its signing secret.
2. A resource changes status, for example an invoice goes from Cancelando (canceling) to Cancelado (canceled), and Fiscalapi records an event.
3. Fiscalapi sends the event by POST to every enabled webhook that subscribes to it, signed with that webhook's secret.
4. Your endpoint verifies the signature, responds with a 2xx, and processes the event afterward. If it doesn't respond with a 2xx, Fiscalapi keeps retrying for about 75 hours.

The event only says which resource changed and which status it reached; it carries no tax details. For the details, fetch the resource with the URL that comes in the event.

Webhooks are included in every tenant (the space in Fiscalapi that holds your issuers, recipients, credits, and data). Managing them requires the Webhooks.Manage permission. The owner (the person who created the tenant) and the other people who sign in to your tenant have it. The API accepts these requests with your API key or with your dashboard session.

Event types

Each type names the status the resource reached, in the form resource.status. Fiscalapi emits one event per transition.

download_request.abandoned doesn't imply an error: the reason is in the request's GET response. A common cause is that the SAT finds no documents that match the criteria. See the details with Get a request by ID and the request lifecycle.

Ignore event types you don't recognize: new types can be added without changing the envelope. A new type arrives with the same shape; respond with a 2xx and discard it.

Status codes

The status and previousStatus fields carry the public API v4 codes, the same ones the resource's GET returns:

The previous status depends on the path the resource took. For example, a request is abandoned from Esperando SAT (waiting for the SAT) or from Esperando API (waiting for the API), and the simulated request in the test environment reaches Completada (completed) with no previous status. Treat both fields as text that can be null.

The event

Every event has the same shape: the envelope. No field belongs to a single type; only the values change between types.

{
  "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"
  }
}

The examples are formatted for readability; the actual body arrives on a single line, without spaces. Because the URL is relative, the same event is identical in test and production. The base URL is https://test.fiscalapi.com in test and https://live.fiscalapi.com in production.

personId can be null, as in an invoice by value (you send every issuer, recipient, and item value in the request), and then the event doesn't reach webhooks with a people filter. An invoice by value has no issuer registered as a person in your tenant, so only webhooks without a people filter receive its event. If you issue invoices by value and want those events, register a webhook without a filter.

Register a webhook

A webhook belongs to your tenant and receives the events of all its people, unless you limit it to some of them. You can have up to 16 URL webhooks per tenant.

To receive events on your computer, use the CLI: see Test your endpoint.

From the dashboard

Go to Developers > Webhooks and click Agregar webhook (Add webhook). Enter the URL, the description, the events (Todos (All) or the types you choose), and, optionally, the people. When you save, the dashboard shows the signing secret with the notice "Guarda este secreto de firma. Lo usarás para verificar que los eventos vienen de FiscalAPI." (Save this signing secret. You'll use it to verify that the events come from Fiscalapi.) Click Copiar (Copy) and store it in your endpoint's secure configuration.

The Webhooks page has these actions:

Reenviar (Resend) and Enviar evento de prueba (Send test event) only appear when the webhook is enabled. Revelar secreto (Reveal secret) and Rotar secreto (Rotate secret) don't appear while someone from support accesses your tenant on your behalf.

With the API

Register the webhook with Create a webhook. The response includes the secret in secret; with the API key, you can only get it again by rotating it, so save it when you receive the response. Then test it with Test a webhook and check the result in List deliveries.

The secret is the whsec_ prefix followed by 44 base64 characters: 32 random bytes, with an equals sign at the end. Store it in full, with its prefix.

Verify the signature

Every delivery follows the open Standard Webhooks specification and carries three headers:

The signature is the only proof that an event is authentic. Fiscalapi doesn't publish its servers' IP addresses or recommend filtering deliveries by IP: those addresses can change without notice. Reject every delivery whose signature doesn't match the one you compute.

The signature is a base64 HMAC-SHA256 over the text {id}.{timestamp}.{body}: the event ID, a period, the timestamp, another period, and the raw body, exactly as they arrive. The HMAC key is the secret without the whsec_ prefix, decoded from base64.

To verify a delivery:

1. Read the raw body, exactly the bytes that arrived, before your framework turns it into an object.
2. Reject the delivery if the timestamp is more than 5 minutes off from your clock. That way, no one can replay a captured delivery later.
3. Compute the signature with each current secret. During a rotation, you have two.
4. Accept the delivery if any v1 signature in the header matches yours. Compare in constant time, never with a regular string comparison.
5. Only then parse the body as JSON and process it.

With the SDK

The official SDKs do these steps for you. Their verification function takes the delivery headers, the raw body, and your secret (or a list of secrets during a rotation), and returns the verified event:

using System.Text;
using System.Threading.Channels;
using Fiscalapi.Models;
using Fiscalapi.Webhooks;

// ASP.NET Core. The current secret and, during a rotation, the previous one too.
var secrets = builder.Configuration.GetSection("FiscalApi:WebhookSecrets").Get<string[]>()!;
var events = Channel.CreateUnbounded<WebhookEvent>(); // for illustration: use a durable queue in production

app.MapPost("/webhooks/fiscalapi", async (HttpRequest request) =>
{
    // The raw body, exactly as it arrived.
    using var reader = new StreamReader(request.Body, Encoding.UTF8);
    var body = await reader.ReadToEndAsync();
    var headers = request.Headers.ToDictionary(h => h.Key, h => h.Value.ToString());

    WebhookEvent webhookEvent;
    try
    {
        webhookEvent = Webhook.Verify(headers, body, secrets);
    }
    catch (WebhookVerificationException)
    {
        return Results.BadRequest(); // invalid signature, missing header, or timestamp outside the tolerance
    }

    await events.Writer.WriteAsync(webhookEvent); // process it later, outside the request
    return Results.Ok();
});

Verification compares in constant time, accepts any valid v1 signature in the header, and rejects a timestamp more than 5 minutes off. If the delivery fails verification, the function throws the verification exception: respond with 400 and don't process the delivery. A miscopied secret or an empty list throws a configuration error, which never includes the secret's value.

The classes live in Fiscalapi.Webhooks in .NET, in com.fiscalapi.webhooks in Java, and in Fiscalapi\Webhooks in PHP. In Node.js, the fiscalapi package exports them.

By hand

Without the SDK, any Standard Webhooks library verifies Fiscalapi deliveries with your secret as is, prefix included. You can also implement the verification with your language's standard library:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

public static class WebhookVerifier
{
    private const long ToleranceSeconds = 5 * 60;

    // id, timestamp, and signature are the webhook-id, webhook-timestamp, and webhook-signature headers.
    // rawBody is the raw body, exactly as it arrived, not deserialized.
    // secrets is a list of whsec_ secrets: the current one and, during a rotation, the previous one too.
    public static JsonDocument Verify(string id, string timestamp, string signature, byte[] rawBody,
        IEnumerable<string> secrets, DateTimeOffset? now = null)
    {
        var nowSeconds = (now ?? DateTimeOffset.UtcNow).ToUnixTimeSeconds();
        if (string.IsNullOrEmpty(id) || !long.TryParse(timestamp, out var seconds) ||
            seconds < nowSeconds - ToleranceSeconds || seconds > nowSeconds + ToleranceSeconds)
            throw new CryptographicException("Timestamp fuera de la tolerancia");

        var content = Encoding.UTF8.GetBytes($"{id}.{timestamp}.").Concat(rawBody).ToArray();
        var expected = secrets
            .Select(secret => Convert.FromBase64String(secret.StartsWith("whsec_") ? secret[6..] : secret))
            .Select(key => HMACSHA256.HashData(key, content))
            .ToList();

        foreach (var entry in (signature ?? "").Split(' '))
        {
            var parts = entry.Split(',', 2);
            var received = new byte[HMACSHA256.HashSizeInBytes];
            if (parts.Length == 2 && parts[0] == "v1" &&
                Convert.TryFromBase64String(parts[1], received, out var written) && written == received.Length &&
                expected.Any(e => CryptographicOperations.FixedTimeEquals(e, received)))
                return JsonDocument.Parse(rawBody);
        }

        throw new CryptographicException("Firma inválida");
    }
}

Test your implementation with the official Standard Webhooks test vector. With the current time set to the vector's timestamp, the signature verifies; if you change one character of the body, the signature, or the secret, it fails:

Respond to a delivery

Each delivery is a POST with Content-Type: application/json; charset=utf-8 and the User-Agent FiscalAPI-Webhooks/1. Fiscalapi waits up to 15 seconds in total for the response, including 5 to connect, and logs the status code and the first KB of the response.

Respond with a 2xx quickly and process the event later. A 3xx counts as a failure, and a 410 disables the webhook. Fiscalapi doesn't follow redirects: if you change the URL, update the webhook.

Store the event in a queue or a table and respond. Do the heavy work, such as fetching the resource or updating your system, outside the request: an endpoint that takes more than 15 seconds piles up retries of events it did receive.

Retries

If a delivery fails, Fiscalapi retries it on this schedule, counted from the previous failure. Each wait varies by up to 10% so that pending deliveries don't all arrive at once.

That's 10 attempts over about 75 hours: an endpoint that's down for a weekend still receives its events. Each attempt carries a new webhook-timestamp and its own signature, with the same webhook-id and the same body. Resends and test deliveries are single attempts and don't follow this schedule.

Delivery is at least once: your endpoint can receive the same event more than once, for example if it responded with a 2xx but the response didn't reach Fiscalapi. Deduplicate by webhook-id: store the IDs you processed and, if a known one arrives, respond with a 2xx without repeating the work.

Order isn't guaranteed: a retry can arrive after a newer event for the same resource. For the authoritative status, send a GET to relatedObject.url with your base URL and your credentials; the API always returns the current status.

Disabling and notifications

Fiscalapi emails the tenant owner when something fails persistently, and it disables webhooks that don't respond:

The dashboard shows why a webhook is disabled: Por ti (By you), El webhook respondió 410 (The webhook responded with 410), or 5 días sin respuestas exitosas (5 days without successful responses). In the API, the reason comes in disabledReason.

Events generated while a webhook is disabled aren't delivered to it, not even after you enable it again. When you enable it, recover what you missed with Reconcile events.

Test your endpoint

Send a test event with Enviar evento de prueba (Send test event) in the dashboard or with Test a webhook. A webhook.test event arrives, signed like any other, only at the webhook you tested. Follow the result in the delivery log.

Test deliveries (the ones from this button, from Test a webhook, and from fiscalapi trigger) behave differently from the others:

Test locally

Fiscalapi doesn't deliver to localhost. To receive events on your computer without exposing it to the internet, use the fiscalapi CLI: it brings your tenant's events to your local server, triggers test events, and resends the ones you missed. Test webhooks locally explains how to install and use it.

Reconcile events

Fiscalapi keeps events and their deliveries for 30 days. After your endpoint goes down, or when you enable a webhook again, List events returns each envelope exactly as it was sent, newest first, with filters by type, resource, and date range.

Compare the id values with the ones you already processed. Process the missing ones from the list, or have them delivered again with Resend an event. A resend is a single attempt and arrives with the same webhook-id, so your deduplication recognizes it. An event older than 30 days can no longer be retrieved or resent.

Rotate the secret

Rotate the secret if it was exposed or as a routine security measure. In the dashboard, Rotar secreto (Rotate secret) asks for this confirmation: "Se generará un secreto nuevo. El actual seguirá firmando durante 24 horas para que actualices tu receptor sin perder eventos. ¿Continuar?" (A new secret will be generated. The current one keeps signing for 24 hours so you can update your endpoint without losing events. Continue?). With the API, call Rotate a secret.

For the next 24 hours, each delivery carries two signatures in webhook-signature, one with the new secret and one with the previous one. To switch secrets without losing events:

1. Rotate the secret and save the new one.
2. Configure your endpoint with both secrets; verification accepts the delivery if either signature matches.
3. Once your endpoint has the new secret, remove the previous one. After 24 hours, the previous one stops signing.

If you rotate again within 24 hours, the previous secret keeps its original expiration and only the new one is replaced. That way, if an endpoint hasn't switched secrets yet, a double click doesn't leave it without a secret.

To see the current secret without rotating it, use Revelar secreto (Reveal secret) in the dashboard. It's only available in the dashboard, not with the API key, and every reveal is logged. While someone from support accesses your tenant on your behalf, no response includes the secret.

Endpoint best practices

Rate limit

Test a webhook, Resend an event, and Trigger a test event, which fiscalapi trigger uses, have a rate limit per API key, shared with the creation of bulk download requests. The dashboard doesn't have this limit. Every response includes your usage in the RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers.

If you exceed it, the API responds with 429 and the Retry-After header, in seconds, and doesn't run the operation. Wait that long and repeat the request. The body of that response is in Dates and errors.

Related resources