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

# Webhooks de Recaudación

> Eventos disponibles para la API de Cobros y cómo recibirlos

## ¿Cómo funcionan los webhooks de cobros?

Cuando cambia el estado de una sesión de cobro, Tupana envía un `POST` firmado a tu endpoint registrado. El sistema de webhooks es el mismo que usan el resto de las APIs — si ya tienes uno configurado, solo necesitas suscribirte a los nuevos eventos.

Para registrar o gestionar tus endpoints de webhook, consulta la sección de [Webhooks](/api-reference/webhooks/webhooks).

## Eventos disponibles

| Evento                            | Cuándo se emite                                                                                                                         |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `payment_request.paid`            | El pago fue confirmado exitosamente. Único evento que se dispara en modo cobro directo.                                                 |
| `payment_request.document_issued` | El DTE fue emitido (automáticamente o vía `PATCH /v1/payment-requests/{id}/` con `status=issued`). No se dispara en modo cobro directo. |
| `payment_request.expired`         | La sesión venció sin pagarse.                                                                                                           |

## Estructura del payload

Todos los eventos de cobro siguen la estructura estándar de webhooks de Tupana:

```json theme={null}
{
  "event": "payment_request.paid",
  "created_at": "2026-04-15T14:03:45Z",
  "data": {
    "payment_request_id": 1042,
    "status": "paid",
    "external_id": "booking_abc123",
    "amount": 50000,
    "target_dte_type": "39",
    "payment_url": "https://www.tupana.ai/pagos/tok_xyz",
    "issued_document_id": 9871,
    "metadata": {},
    "document_ids": []
  }
}
```

### Campos de `data`

| Campo                | Descripción                                                                                    |
| -------------------- | ---------------------------------------------------------------------------------------------- |
| `payment_request_id` | ID numérico de la sesión de cobro.                                                             |
| `status`             | Estado resultante (`paid`, `expired`).                                                         |
| `external_id`        | Tu ID propio para esta sesión. `null` si no enviaste uno.                                      |
| `amount`             | Monto del cobro en CLP.                                                                        |
| `target_dte_type`    | Tipo de DTE configurado para la sesión. `null` en modo cobro directo.                          |
| `payment_url`        | URL de pago de la sesión.                                                                      |
| `issued_document_id` | ID del DTE emitido. `null` si el DTE aún no fue emitido o si la sesión es modo cobro directo.  |
| `metadata`           | Datos adicionales que enviaste al crear la sesión.                                             |
| `document_ids`       | IDs de los documentos que esta sesión cobró (modo cobro directo). Lista vacía en modo emisión. |

### Ejemplo en modo cobro directo

```json theme={null}
{
  "event": "payment_request.paid",
  "created_at": "2026-04-15T14:03:45Z",
  "data": {
    "payment_request_id": 1099,
    "status": "paid",
    "external_id": "collection_session_001",
    "amount": 75000,
    "target_dte_type": null,
    "payment_url": "https://www.tupana.ai/pagos/tok_def",
    "issued_document_id": null,
    "metadata": { "campaign": "cobranza-abril" },
    "document_ids": [9871, 9872]
  }
}
```

## Headers

Cada notificación incluye los siguientes headers:

```http theme={null}
Content-Type: application/json
X-Pana-Event-Type: payment_request.paid
X-Pana-Event-Id: <uuid>
X-Pana-Timestamp: 2026-04-15T14:03:45Z
X-Pana-Delivery: <delivery-uuid>
X-Pana-Signature: <firma-hmac>
```

## Verificar la firma

Verifica que el webhook proviene realmente de Tupana usando el `secret` que recibiste al registrar el endpoint.

```python theme={null}
import hmac
import hashlib
import json

def verify_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        json.dumps(payload, sort_keys=True).encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected, signature)

# En tu endpoint:
signature = request.headers.get('X-Pana-Signature')
is_valid = verify_signature(request.json, signature, os.environ['TUPANA_WEBHOOK_SECRET'])

if not is_valid:
    return {'error': 'Invalid signature'}, 401
```

```javascript theme={null}
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

const signature = req.headers['x-pana-signature'];
const isValid = verifySignature(req.body, signature, process.env.TUPANA_WEBHOOK_SECRET);

if (!isValid) {
  return res.status(401).json({ error: 'Invalid signature' });
}
```

## Reintentos

Tu endpoint debe responder con `2xx` en menos de **120 segundos**. Si no responde o devuelve error, Tupana reintenta con backoff:

| Intento | Tiempo de espera   |
| ------- | ------------------ |
| 2       | 1 minuto después   |
| 3       | 5 minutos después  |
| 4       | 15 minutos después |
| 5       | 1 hora después     |
| 6       | 6 horas después    |

Cada entrega tiene un `X-Pana-Delivery` único. Si recibes el mismo ID dos veces, es un reintento del mismo evento — tu endpoint debe ser idempotente.

<Tip>
  Usa el evento `webhook.test` disponible en el panel de Tupana para verificar que tu endpoint está recibiendo correctamente antes de ir a producción.
</Tip>