> For the complete documentation index, see [llms.txt](https://docs.qentaz.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qentaz.com/documentation/webhooks/eventos-de-dispersiones.md).

# Eventos de dispersiones

En estos eventos te notificaremos cada vez que ocurra un cambio de estado en tus dispersiones a terceros. Los estados que se notifican son los siguientes:

<table><thead><tr><th width="153.03515625">event.status</th><th>Descripción</th><th width="215.95703125">detail.status</th></tr></thead><tbody><tr><td><code>success</code></td><td>Cuando la dispersión fue confirmada por la entidad bancaria del destinatario. (*Colombia: esta confirmación puede demorar entre 4 y 6 horas hábiles después de la recepción del dinero, por los ciclos ACH)</td><td>SUCCESS<br><code>Exitosa</code></td></tr><tr><td><code>confirm</code></td><td>Caso equivalente a <code>success</code> para dispersiones con autorización por token: se dispara al confirmarse la dispersión con el token recibido.</td><td>SUCCESS<br><code>Exitosa</code></td></tr><tr><td><code>failed</code></td><td>Cuando la dispersión no pudo completarse.</td><td>FAILED<br><code>Fallida</code></td></tr><tr><td><code>cancel</code></td><td>Cuando la dispersión fue cancelada.</td><td>CANCELED<br><code>Cancelada</code></td></tr><tr><td><code>edit</code></td><td>Cuando la dispersión fue modificada. Este evento no corresponde a un estado de la dispersión, por lo que <code>detail.status</code> puede llegar con cualquier valor.</td><td>-</td></tr></tbody></table>

## Encabezado

<table><thead><tr><th width="231.90625">Nombre</th><th>Contenido</th></tr></thead><tbody><tr><td><code>Authorization</code></td><td>Bearer {integration_key}</td></tr><tr><td><code>X-Trazo-Signature</code></td><td>timestamp={timestamp},signature={firma}</td></tr><tr><td><code>X-Trazo-Event-Id</code></td><td>Identificador único del evento</td></tr><tr><td><code>X-Trazo-Event-Attempt</code></td><td>Número de intento: 1, 2 o 3</td></tr><tr><td><code>Content-Type</code></td><td>application/json</td></tr></tbody></table>

Si configuraste un encabezado personalizado para tu comercio, este se envía además de los anteriores con el nombre y el valor que hayas definido.

{% hint style="info" %}
Cómo validar la firma, la política de reintentos y el uso del `event_id` para identificar reintentos son iguales para todos los eventos de Trazo: encontrarás el detalle en la [Introducción](/documentation/webhooks/introduccion.md).
{% endhint %}

## Payload

{% code overflow="wrap" %}

```json
{
    "event_id": "7f3b1c2d-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
    "event": {
        "type": "payout",
        "status": "success"
    },
    "created_at": "2025-03-15 16:49:02.891",
    "external_reference": "a1a2a3a4",
    "detail": {
        "amount": "29900",
        "currency": "COP",
        "description": "Ejemplo dispersión exitosa",
        "reference_one": "REF1",
        "reference_two": "REF2",
        "reference_three": "REF3",
        "reference_four": "REF4",
        "channel": "WHATSAPP",
        "status": "SUCCESS",
        "payment_method": "manual",
        "payment_method_source": "bancolombia",
        "process_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "url_receipt": "https://content.qentaz.com/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/a1a2a3.pdf",
        "creator": {
            "name": "Comercio Ejemplo",
            "first_name": null,
            "last_name": null,
            "phone": "573998887777",
            "email": "comercio@qentaz.com",
            "id_number": "900123456"
        },
        "approver": {
            "name": null,
            "first_name": "Ana",
            "last_name": "Gomez",
            "id_number": "1122334455",
            "phone": "573887779999",
            "email": "ana@comercioejemplo.com",
            "date": "2025-03-14",
            "signature": "Qentaz.sdamd012fmoci209008120833f9d0129fj10f21=="
        },
        "receiver": {
            "first_name": "Nombre",
            "last_name": "Apellido",
            "business_name": "",
            "id_type": "CC",
            "id_number": "1234567890",
            "id_number_dv": null,
            "phone": "573778889999",
            "email": "test@qentaz.com",
            "bank_name": "Bancolombia",
            "account_number": "12345678",
            "account_type": "SAVINGS"
        },
        "invoicing": {
            "provider": null,
            "type": null,
            "bill_id": null,
            "bill_number": null,
            "voucher": {
                "id": null,
                "number": null
            }
        }
    }
}
```

{% endcode %}

{% hint style="info" %}
`creator` es quien generó la dispersión; `approver` es quien la autorizó. `approver` llega con todos sus campos en `null` cuando la dispersión aún no tiene una aprobación registrada (por ejemplo, mientras está pendiente).
{% endhint %}

{% hint style="info" %}
El bloque `invoicing` viaja siempre, aunque el comercio no tenga facturación electrónica configurada para dispersiones — en ese caso llega con sus campos en `null`, como en el ejemplo.
{% endhint %}

### Detalle del evento de modificación

A diferencia de los demás eventos, en `edit` el objeto `detail` **no** trae la foto completa de la dispersión. Trae únicamente los campos que cambiaron, con su valor nuevo.

{% hint style="info" %}
Este evento se dispara después de que el cambio ya se aplicó, así que no hay forma de incluir el valor anterior del campo — solo reportamos lo que cambió y a qué quedó.
{% endhint %}

{% code overflow="wrap" %}

```json
{
    "event_id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
    "event": {
        "type": "payout",
        "status": "edit"
    },
    "created_at": "2025-03-15 16:49:02.891",
    "external_reference": "a1a2a3a4",
    "detail": {
        "amount": "35000"
    }
}
```

{% endcode %}