¿Cómo funcionan los webhooks de cobros?
Cuando cambia el estado de una sesión de cobro, Tu Pana 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 Tu Pana:
{
"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]
}
}
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 Tu Pana 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, Tu Pana 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 |
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 Tu Pana para verificar que tu endpoint está recibiendo correctamente antes de ir a producción.
