Webhooks de Recaudación

¿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.

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:

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

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

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.

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

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.

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.

Introducción

Cuenta Bancaria

Medios de pago

Liquidaciones

Cobros

Webhooks

Referencia

Webhooks de Recaudación

¿Cómo funcionan los webhooks de cobros?

Eventos disponibles

Estructura del payload

Campos de `data`

Ejemplo en modo cobro directo

Headers

Verificar la firma

Reintentos

​¿Cómo funcionan los webhooks de cobros?

​Eventos disponibles

​Estructura del payload

​Campos de data

​Ejemplo en modo cobro directo

​Headers

​Verificar la firma

​Reintentos

¿Cómo funcionan los webhooks de cobros?

Eventos disponibles

Estructura del payload

Campos de `data`

Ejemplo en modo cobro directo

Headers

Verificar la firma

Reintentos