Recupera los eventos que perdiste

Al final de esta guía, tu aplicación puede reconstruir el estado que perdió mientras tu webhook endpoint no recibía eventos. Tu endpoint pierde eventos cuando tu servidor está caído, cuando tu handler falla después de que Fintoc registra la entrega, o cuando un deploy descarta requests. Fintoc guarda cada evento que genera para tu organización, así consultas la ventana que perdiste y la procesas por tu cuenta.

Identifica la ventana que perdiste

Define dos momentos: el último evento que procesó tu aplicación y la hora en que tu endpoint volvió a responder. Si guardas el id de cada evento como recomienda la página de buenas prácticas, toma el primer momento de tus propios registros. Si no, usa el inicio y el final del incidente. Una ventana más amplia que la caída es segura cuando tu handler es idempotente, porque un evento que ya procesaste no genera trabajo adicional.

Lista los eventos de esa ventana

Llama a Listar eventos con la ventana en since y until. Ambos aceptan una fecha como 2026-01-15 o un datetime ISO 8601 como 2026-01-15T09:00:00Z. Tu API key define el modo: una key de test devuelve eventos de test y una de live devuelve eventos de live.

Server

curl --request GET \
  --url 'https://api.fintoc.com/v2/events?since=2026-01-15T09:00:00Z&until=2026-01-15T11:30:00Z&limit=100' \
  --header 'Authorization: YOUR_API_KEY'

Response

[
  {
    "id": "evt_0ujsswThIGTUYm2K8FjOOfXtY1K",
    "object": "event",
    "created_at": "2026-01-15T10:30:00.000Z",
    "data": {
      "id": "tr_0ujsswThIGTUYm2K8FjOOfXtY1K",
      "object": "transfer",
      "amount": 5000,
      "currency": "clp",
      "status": "succeeded"
    },
    "mode": "live",
    "type": "transfer.outbound.succeeded"
  }
]

Cada evento contiene en data el mismo payload que Fintoc envió a tu endpoint, así que tu handler lo acepta sin cambios. Acota más la ventana cuando sabes qué perdiste:

type filtra la respuesta a un tipo de evento, como transfer.outbound.succeeded.
resource_id filtra la respuesta a los eventos de un recurso, como una transferencia o un payment intent.

Pagina los resultados

limit devuelve hasta 300 eventos por página y por defecto son 30. Mientras queden eventos, la respuesta incluye un header Link con la URL de la página siguiente y rel="next". Sigue esa URL, o envía starting_after con el id del último evento que recibiste.

Server

curl --request GET \
  --url 'https://api.fintoc.com/v2/events?since=2026-01-15T09:00:00Z&until=2026-01-15T11:30:00Z&limit=100&starting_after=evt_0ujsswThIGTUYm2K8FjOOfXtY1K' \
  --header 'Authorization: YOUR_API_KEY'

Response

[
  {
    "id": "evt_2b7QpLmNvR4sT8dWxYzC3fGhJ5K",
    "object": "event",
    "created_at": "2026-01-15T09:47:12.884Z",
    "data": {
      "id": "tr_9xKmPq2RtVn5WbY7cD4fH8jL3sN",
      "object": "transfer",
      "amount": 250000,
      "currency": "clp",
      "status": "succeeded"
    },
    "mode": "live",
    "type": "transfer.outbound.succeeded"
  }
]

Los eventos llegan del más nuevo al más antiguo, así que cada página avanza más atrás en el tiempo. La última página llega sin header Link.

Reprocesa los eventos

Entrega cada evento al handler que ya procesa los webhooks en vivo. Reutilizar el handler mantiene los dos caminos de acuerdo sobre cómo un evento actualiza tu aplicación.

const handleEvent = require('./handleEvent');

const reprocess = async (pages) => {
  const events = pages.flat().reverse();

  for (const event of events) {
    await handleEvent(event);
  }
};

from handle_event import handle_event


def reprocess(pages):
    events = [event for page in pages for event in page]

    for event in reversed(events):
        handle_event(event)

Junta todas las páginas antes de procesarlas y después invierte la lista completa. La API devuelve cada página con el evento más nuevo primero, y la paginación avanza hacia atrás en el tiempo.

Prueba la recuperación

Ejecuta la recuperación en modo test antes de depender de ella:

Detén tu webhook endpoint y envía eventos de prueba desde el dashboard.
Lista esos eventos con tu API key de test y la ventana que acabas de crear.
Levanta tu endpoint de nuevo y ejecuta la recuperación sobre la respuesta.

Tu aplicación queda en el mismo estado que si hubiera recibido los eventos en vivo.

​Identifica la ventana que perdiste

​Lista los eventos de esa ventana

​Pagina los resultados

​Reprocesa los eventos

​Prueba la recuperación

Identifica la ventana que perdiste

Lista los eventos de esa ventana

Pagina los resultados

Reprocesa los eventos

Prueba la recuperación