---
title: "Webhooks"
description: "Recibir eventos normalizados, firmados, duplicables y potencialmente fuera de orden."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.pagofast.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

# Webhooks

PagoFast envía eventos normalizados a la URL configurada por el integrador. La entrega es asíncrona: puede ocurrir después de la respuesta REST y no reemplaza la consulta del recurso para reconciliación.

## Configuración del destino

Cuando `POST /v1/payments` admite `webhook_url`, esa URL recibe los eventos del pago. Si el ambiente ofrece endpoints de webhook a nivel cuenta, su configuración se administra por separado. No asumas que ambos mecanismos existen: confirmalo en el OpenAPI desplegado.

Usá HTTPS, evitá redirects y no incluyas secretos en la query string. El endpoint debe aceptar el body JSON crudo y los headers de firma.

## Eventos

```text
payment.pending
payment.approved
payment.declined
payment.failed
payment.expired
payment.canceled
payment.refunded
```

Los clientes deben aceptar tipos nuevos sin fallar todo el endpoint. Registrá de manera segura un tipo desconocido y respondé según la política acordada, sin aplicar un cambio de negocio que no comprendés.

## Payload

```json
{
  "id": "evt_019f7067f8b47b4e",
  "type": "payment.approved",
  "created_at": "2026-07-17T13:15:08.500Z",
  "data": {
"payment": {
  "id": "019f7061-2010-7698-8827-e32f86e14298",
  "status": "approved",
  "amount": {
    "value": "12500.00",
    "currency": "ARS"
  },
  "external_reference": "order-9821",
  "payment_method": "019f704f-89d7-7e83-b3e1-f07c33801024",
  "processor_reference": "trx_739204",
  "updated_at": "2026-07-17T13:15:08.441Z"
}
  }
}
```

`id` identifica el evento y se mantiene en reintentos o replay. `created_at` es la creación del evento; `payment.updated_at` indica la versión temporal del recurso.

## Headers

Cada delivery incluye como mínimo los headers usados para identificación y firma:

```http
OrderFast-Event-Id: evt_019f7067f8b47b4e
OrderFast-Timestamp: 1784294108
OrderFast-Signature: v1=0c240b7f...
```

El nombre histórico de los headers es parte del contrato y puede diferir del nombre comercial PagoFast. Verificá siempre la [firma](/webhooks/signatures) antes de procesar el payload.

## Handler recomendado

1. Leer el body crudo sin modificarlo.
2. Validar timestamp y firma.
3. Parsear JSON y verificar su estructura.
4. Iniciar una transacción local.
5. Insertar `event.id` con una restricción única.
6. Si ya existe, responder `2xx` sin repetir efectos.
7. Aplicar una transición válida usando `payment.updated_at`.
8. Persistir y confirmar.
9. Responder `2xx` rápidamente.
10. Ejecutar trabajo lento de forma asíncrona en tu sistema.

Ejemplo conceptual:

```text
if !valid_signature(raw_body, headers): return 401
event = parse(raw_body)
if events.exists(event.id): return 204
save_event_and_apply_valid_transition(event)
return 204
```

## Duplicados y orden

La entrega es al menos una vez: el mismo evento puede llegar varias veces. Eventos distintos pueden llegar fuera de orden. No deduzcas el estado solo por `type`; compará la versión del recurso y evitá retroceder desde un estado final.

Si no podés decidir una transición con seguridad, conservá el evento y consultá `GET /v1/payments/{payment_id}`.

## Respuestas

Cualquier status `2xx` confirma recepción y detiene los reintentos de esa entrega. Respondé `4xx` para requests inválidos y `5xx` cuando una falla temporal impida persistirlos, teniendo en cuenta la [política de reintentos](/webhooks/retries).

No devuelvas información sensible ni detalles internos en el body de respuesta.

Source: https://docs.pagofast.com/webhooks/overview/index.mdx