Webhooks

Los webhooks de Tupana te permiten recibir notificaciones en tiempo real cuando ocurren eventos importantes en tu sistema de facturación. Esta guía te ayudará a configurar y usar webhooks de forma efectiva.

¿Qué son los webhooks?

Los webhooks son una forma de comunicación donde Tupana envía automáticamente una notificación HTTP POST a una URL que tú configures cuando ocurre un evento específico (por ejemplo, cuando se emite una factura). A diferencia de las APIs donde tú haces las consultas, con los webhooks Tupana te notifica cuando algo importante sucede, permitiéndote mantener tu sistema sincronizado en tiempo real.

Cómo crear un webhook

Desde la interfaz web

Ve a Configuración → Webhooks
Haz clic en Nuevo Webhook
Completa los siguientes campos:
- URL del Endpoint: La URL de tu servidor que recibirá las notificaciones (debe ser HTTPS)
- Eventos: Selecciona los eventos que quieres recibir
- Secret (opcional): Una clave secreta para verificar la autenticidad de las notificaciones
- Ambiente: Producción y sandbox (default), sólo producción o sólo sandbox
- Formato de identificadores: Públicos (docu_…, ment_…, recomendado) o enteros (API v1). Viene preseleccionado según los webhooks que ya tiene la empresa. Ver Identificadores en el payload
- Activo: Marca esta opción para activar el webhook
Haz clic en Guardar

Ejemplo de configuración

URL: https://mi-servidor.com/webhooks/tupana
Eventos: document.issued, document.paid
Secret: mi_clave_secreta_123
Activo: ✓

Seguridad

Firma de webhooks

Para verificar que las notificaciones provienen realmente de Tupana, puedes configurar un secret al crear el webhook. Tupana firmará cada notificación usando HMAC SHA-256.

Cómo verificar la firma

Node.js:

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)
  );
}

// En tu endpoint
const signature = req.headers['x-pana-signature'];
const isValid = verifySignature(req.body, signature, process.env.WEBHOOK_SECRET);

if (!isValid) {
  return res.status(401).send('Invalid signature');
}

Python:

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['WEBHOOK_SECRET'])

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

Headers enviados

Cada notificación incluye los siguientes headers:

Content-Type: application/json
User-Agent: Pana-Webhook/1.0
X-Pana-Event-Id: ID único del evento (UUID)
X-Pana-Event-Type: Tipo de evento (ej: document.issued)
X-Pana-Timestamp: Timestamp ISO 8601 del evento
X-Pana-Delivery: ID único del intento de entrega (UUID)
X-Pana-Signature: Firma HMAC SHA-256 (si configuraste un secret)

Eventos soportados

Eventos de documentos

document.issued: Se emitió un documento exitosamente
document.issue_failed: Falló la emisión de un documento
document.updated: Se actualizó un documento existente
document.delivered: Se entregó un documento (PDF/XML enviado al cliente)
document.rejected: El SII rechazó el documento
document.paid: El documento fue pagado (conciliación bancaria)
document.unpaid: El documento volvió de pagado a no pagado (se revirtió el pago/conciliación)
document.cancelled: El documento fue anulado o tiene nota de crédito
document.trace_updated: Apareció un evento nuevo en la traza del SII (acuse de recibo, reclamo, rechazo). Es el único evento que se notifica tanto al emisor como al receptor del documento

Eventos de documentos programados

scheduled_document.created: Se creó un documento programado
scheduled_document.updated: Se actualizó un documento programado
scheduled_document.run_started: Se inició la ejecución de un documento programado
scheduled_document.run_succeeded: La ejecución de un documento programado fue exitosa
scheduled_document.run_failed: La ejecución de un documento programado falló

Eventos de credenciales

credential.validated: Una credencial SII fue validada exitosamente contra el SII
credential.invalid: Una credencial SII quedó inválida (clave incorrecta o cuenta bloqueada)

Eventos operacionales

webhook.test: Evento de prueba para verificar que tu endpoint funciona correctamente

Payloads por Evento

Cada evento tiene una estructura de payload específica. Navega a cada evento para ver su payload completo:

Navegación Rápida

Eventos de Documentos
Eventos de Documentos Programados
Eventos de Credenciales
- credential.validated
- credential.invalid
Eventos Operacionales
- webhook.test

Eventos de Documentos

document.issued

Se dispara cuando un documento se emite exitosamente. Incluye el PDF y XML del documento.

{
  "event": "document.issued",
  "created_at": "2026-01-19T15:30:45.123456Z",
  "data": {
    "id": "docu_8371029384756",
    "folio": "12345",
    "date_issued": "2026-01-19",
    "amount_with_iva": 119000.0,
    "is_sandbox": false,
    "dte_type": {
      "code": "33",
      "description": "Factura Electrónica"
    },
    "sender": {
      "id": "ment_4829301923847",
      "name": "Empresa Emisora S.A.",
      "tax_id": "76.123.456-7",
      "email": "contacto@empresa.cl"
    },
    "receiver": {
      "id": "ment_7710084398120",
      "name": "Cliente Receptor S.A.",
      "tax_id": "77.987.654-3",
      "email": "contacto@cliente.cl"
    },
    "document_issuer": {
      "rut": "76.123.456-7",
      "business_name": "Empresa Emisora S.A.",
      "business_activity": "Desarrollo de Software",
      "phone_number": "+56912345678",
      "email": "contacto@empresa.cl",
      "activity_code": "620100",
      "sii_branch_code": "0",
      "address": "Av. Providencia 123",
      "district": "Providencia",
      "city": "Santiago"
    },
    "document_receiver": {
      "rut": "77.987.654-3",
      "business_name": "Cliente Receptor S.A.",
      "business_activity": "Servicios",
      "contact": "Juan Pérez",
      "address": "Av. Las Condes 456",
      "district": "Las Condes",
      "city": "Santiago"
    },
    "document_total": {
      "net_amount": 100000.0,
      "iva_rate": 19.0,
      "iva_amount": 19000.0,
      "total_amount": 119000.0
    },
    "details": [
      {
        "line_number": 1,
        "item_name": "Servicio de desarrollo",
        "item_description": "Desarrollo de aplicación web",
        "quantity": 1.0,
        "unit_price": 100000.0,
        "item_code": "SERV001",
        "item_type_code": "1",
        "unit": "UN",
        "discount_percent": null,
        "other_tax": null
      }
    ],
    "references": [],
    "json_param": null,
    "additional_info": null,
    "pdf_file": "https://s3.amazonaws.com/bucket/documento.pdf",
    "xml_file": "https://s3.amazonaws.com/bucket/documento.xml"
  }
}

Campos específicos:

pdf_file: URL del PDF del documento (solo en este evento)
xml_file: URL del XML del documento
document_issuer: Información completa del emisor
document_receiver: Información completa del receptor
details: Array con todas las líneas del documento

document.issue_failed

Se dispara cuando falla la emisión de un documento.

{
  "event": "document.issue_failed",
  "created_at": "2026-01-19T15:30:45.123456Z",
  "data": {
    "id": "docu_8371029384756",
    "folio": null,
    "date_issued": "2026-01-19",
    "amount_with_iva": 119000.0,
    "is_sandbox": false,
    "dte_type": {
      "code": "33",
      "description": "Factura Electrónica"
    },
    "sender": {
      "id": "ment_4829301923847",
      "name": "Empresa Emisora S.A.",
      "tax_id": "76.123.456-7",
      "email": "contacto@empresa.cl"
    },
    "receiver": {
      "id": "ment_7710084398120",
      "name": "Cliente Receptor S.A.",
      "tax_id": "77.987.654-3",
      "email": "contacto@cliente.cl"
    },
    "document_total": {
      "net_amount": 100000.0,
      "iva_rate": 19.0,
      "iva_amount": 19000.0,
      "total_amount": 119000.0
    },
    "details": [ /* array de detalles completo */ ],
    "xml_file": null,
    "pdf_file": null
  }
}

Nota: En este evento, folio, pdf_file y xml_file pueden ser null ya que el documento no se emitió exitosamente.

document.updated

Se dispara cuando se actualiza un documento existente.

{
  "event": "document.updated",
  "created_at": "2026-01-19T15:30:45.123456Z",
  "data": {
    "id": "docu_8371029384756",
    "folio": "12345",
    "date_issued": "2026-01-19",
    "amount_with_iva": 119000.0,
    "is_sandbox": false,
    "dte_type": {
      "code": "33",
      "description": "Factura Electrónica"
    },
    "sender": { /* objeto sender completo */ },
    "receiver": { /* objeto receiver completo */ },
    "document_total": { /* objeto document_total completo */ },
    "details": [ /* array de detalles completo */ ],
    "xml_file": "https://s3.amazonaws.com/bucket/documento.xml",
    "pdf_file": null
  }
}

Nota: pdf_file puede ser null en este evento ya que solo se genera en la emisión inicial.

document.delivered

Se dispara cuando se entrega un documento (PDF/XML enviado al cliente).

{
  "event": "document.delivered",
  "created_at": "2026-01-19T15:30:45.123456Z",
  "data": {
    "id": "docu_8371029384756",
    "folio": "12345",
    "date_issued": "2026-01-19",
    "amount_with_iva": 119000.0,
    "dte_type": { /* objeto dte_type completo */ },
    "sender": { /* objeto sender completo */ },
    "receiver": { /* objeto receiver completo */ },
    "document_total": { /* objeto document_total completo */ },
    "details": [ /* array de detalles completo */ ],
    "xml_file": "https://s3.amazonaws.com/bucket/documento.xml",
    "pdf_file": null
  }
}

document.rejected

Se dispara cuando el SII rechaza un documento.

{
  "event": "document.rejected",
  "created_at": "2026-01-19T15:30:45.123456Z",
  "data": {
    "id": "docu_8371029384756",
    "folio": "12345",
    "date_issued": "2026-01-19",
    "amount_with_iva": 119000.0,
    "dte_type": { /* objeto dte_type completo */ },
    "sender": { /* objeto sender completo */ },
    "receiver": { /* objeto receiver completo */ },
    "document_total": { /* objeto document_total completo */ },
    "details": [ /* array de detalles completo */ ],
    "xml_file": "https://s3.amazonaws.com/bucket/documento.xml",
    "pdf_file": null
  }
}

document.paid

Se dispara cuando un documento es pagado (conciliación bancaria).

{
  "event": "document.paid",
  "created_at": "2026-01-19T15:30:45.123456Z",
  "data": {
    "id": "docu_8371029384756",
    "folio": "12345",
    "date_issued": "2026-01-19",
    "amount_with_iva": 119000.0,
    "dte_type": { /* objeto dte_type completo */ },
    "sender": { /* objeto sender completo */ },
    "receiver": { /* objeto receiver completo */ },
    "document_total": { /* objeto document_total completo */ },
    "details": [ /* array de detalles completo */ ],
    "xml_file": "https://s3.amazonaws.com/bucket/documento.xml",
    "pdf_file": null
  }
}

document.unpaid

Se dispara cuando un documento que estaba pagado vuelve a no pagado, es decir, cuando se revierte el pago o la conciliación (manualmente o porque una nota de crédito / recálculo de saldo dejó la factura con saldo pendiente). El payload es idéntico al de document.paid; solo cambia el campo event.

{
  "event": "document.unpaid",
  "created_at": "2026-01-19T15:30:45.123456Z",
  "data": {
    "id": "docu_8371029384756",
    "folio": "12345",
    "date_issued": "2026-01-19",
    "amount_with_iva": 119000.0,
    "dte_type": { /* objeto dte_type completo */ },
    "sender": { /* objeto sender completo */ },
    "receiver": { /* objeto receiver completo */ },
    "document_total": { /* objeto document_total completo */ },
    "details": [ /* array de detalles completo */ ],
    "xml_file": "https://s3.amazonaws.com/bucket/documento.xml",
    "pdf_file": null
  }
}

document.cancelled

Se dispara cuando un documento es anulado o tiene una nota de crédito asociada.

{
  "event": "document.cancelled",
  "created_at": "2026-01-19T15:30:45.123456Z",
  "data": {
    "id": "docu_8371029384756",
    "folio": "12345",
    "date_issued": "2026-01-19",
    "amount_with_iva": 119000.0,
    "dte_type": { /* objeto dte_type completo */ },
    "sender": { /* objeto sender completo */ },
    "receiver": { /* objeto receiver completo */ },
    "document_total": { /* objeto document_total completo */ },
    "details": [ /* array de detalles completo */ ],
    "references": [
      {
        "reference_type": {"code": "1"},
        "reference_folio": "54321",
        "reference_date": "2026-01-18",
        "reference_reason": "Anulación"
      }
    ],
    "xml_file": "https://s3.amazonaws.com/bucket/documento.xml",
    "pdf_file": null
  }
}

Nota: El campo references puede contener información sobre la nota de crédito o anulación asociada.

document.trace_updated

Se dispara cada vez que aparece un evento nuevo en la traza del SII de un documento: un acuse de recibo, un reclamo, un rechazo o el vencimiento del plazo de mérito ejecutivo.

Es el único evento que se notifica a las dos puntas del documento. El resto de los eventos de documento se envían al emisor; este también le llega al receptor, para que puedas seguir la traza tanto de lo que emites como de lo que recibes. El campo role te dice desde qué lado estás mirando:

"issuer": tu empresa emitió el documento (lo ves en tus emitidos).
"receiver": tu empresa recibió el documento (lo ves en tus recibidos).

Si ambas puntas son clientes de Tupana y las dos están suscritas, cada una recibe su propia notificación con su propio role.

{
  "event": "document.trace_updated",
  "created_at": "2026-01-19T15:30:45.123456Z",
  "data": {
    "id": "docu_8371029384756",
    "folio": "12345",
    "date_issued": "2026-01-19",
    "amount_with_iva": 119000.0,
    "dte_type": { /* objeto dte_type completo */ },
    "sender": { /* objeto sender completo */ },
    "receiver": { /* objeto receiver completo */ },
    "document_total": { /* objeto document_total completo */ },
    "details": [ /* array de detalles completo */ ],
    "xml_file": "https://s3.amazonaws.com/bucket/documento.xml",
    "role": "receiver",
    "trace": {
      "id": "trac_6120394857261",
      "date_reception": "2026-01-19T12:03:11-03:00",
      "has_acknowledgments": true,
      "has_claims": false,
      "is_rejected": false,
      "is_paid_cash": false,
      "is_more_than_eight_days": false,
      "days_until_executive_merit": 6,
      "new_events": [
        {
          "code": "ACD",
          "description": "Acuse de recibo",
          "date": "2026-01-19T15:29:58-03:00",
          "responsable_tax_id": "76798398-0"
        }
      ],
      "events": [
        {
          "code": "ACD",
          "description": "Acuse de recibo",
          "date": "2026-01-19T15:29:58-03:00",
          "responsable_tax_id": "76798398-0"
        }
      ]
    }
  }
}

Campos de `trace`

id: ID de la traza en Tupana (integer)
date_reception: Fecha y hora en que el SII recibió el documento (string ISO 8601 o null)
has_acknowledgments: El documento tiene acuse de recibo (boolean)
has_claims: El documento tiene reclamos (boolean)
is_rejected: Hay al menos un evento de rechazo (RCD, RFP o RFT) en la traza (boolean)
is_paid_cash: El documento fue pagado al contado (boolean)
is_more_than_eight_days: Pasaron más de 8 días desde la recepción (boolean)
days_until_executive_merit: Días que faltan para el mérito ejecutivo (integer o null; es null si ya hay acuse o rechazo)
new_events: Los eventos que gatillaron esta notificación. Es lo que cambió desde el aviso anterior (array)
events: Todos los eventos de la traza, ordenados por fecha. Te sirve para reconstruir el historial completo si te perdiste alguna entrega (array)

Cada evento de la traza trae:

code: Código del evento en el SII (string)
description: Descripción del evento (string)
date: Fecha y hora del evento (string ISO 8601)
responsable_tax_id: RUT de quien registró el evento (string o null)

Códigos de evento del SII

Código	Significado	Efecto
`ACD`	Acuse de recibo de la mercadería o servicio	El receptor aceptó el documento
`ERM`	Acuse de recibo electrónico (mercaderías)	Corre el plazo de mérito ejecutivo
`RCD`	Reclamo al contenido del documento	`is_rejected: true`
`RFP`	Reclamo por falta parcial de mercaderías	`is_rejected: true`
`RFT`	Reclamo por falta total de mercaderías	`is_rejected: true`
`PAG`	Registro de pago	Informativo

Los códigos los define el SII y pueden aparecer otros que no estén en esta tabla. Trata cualquier código desconocido como informativo en vez de fallar: lo que determina si el documento quedó rechazado es is_rejected.

Cuándo se envía

Se envía un evento por cada evento nuevo de la traza, no uno por actualización. Tupana consulta la traza de tus documentos varias veces al día; mientras no haya novedad, no recibes nada.
Un mismo evento del SII notifica una sola vez, por más veces que se vuelva a consultar la traza. Los reintentos por fallas de tu endpoint sí repiten el envío, con el mismo delivery_id (ver Idempotencia).
xml_file viaja sólo si el XML ya está guardado en Tupana; si no, va en null. Este evento no dispara la descarga del archivo desde el SII.

Eventos de Documentos Programados

scheduled_document.created

Se dispara cuando se crea un documento programado.

{
  "event": "scheduled_document.created",
  "created_at": "2026-01-19T15:30:45.123456Z",
  "data": {
    "id": "scdo_2938475610293",
    "frequency": "monthly",
    "status": "active",
    "sender": {
      "id": "ment_4829301923847",
      "name": "Empresa Emisora S.A.",
      "tax_id": "76.123.456-7"
    },
    "receiver": {
      "id": "ment_7710084398120",
      "name": "Cliente Receptor S.A.",
      "tax_id": "77.987.654-3"
    },
    "dte_type": {
      "code": "33",
      "description": "Factura Electrónica"
    },
    "next_execution": "2026-02-01T00:00:00Z"
  }
}

Campos específicos:

frequency: Frecuencia de ejecución (daily, weekly, monthly, etc.)
status: Estado del documento programado (active, paused, etc.)
next_execution: Fecha y hora de la próxima ejecución

scheduled_document.updated

Se dispara cuando se actualiza un documento programado.

{
  "event": "scheduled_document.updated",
  "created_at": "2026-01-19T15:30:45.123456Z",
  "data": {
    "id": "scdo_2938475610293",
    "frequency": "monthly",
    "status": "active",
    "sender": { /* objeto sender completo */ },
    "receiver": { /* objeto receiver completo */ },
    "dte_type": { /* objeto dte_type completo */ },
    "next_execution": "2026-02-01T00:00:00Z"
  }
}

scheduled_document.run_started

Se dispara cuando se inicia la ejecución de un documento programado.

{
  "event": "scheduled_document.run_started",
  "created_at": "2026-01-19T15:30:45.123456Z",
  "data": {
    "id": "scdo_2938475610293",
    "frequency": "monthly",
    "status": "running",
    "sender": { /* objeto sender completo */ },
    "receiver": { /* objeto receiver completo */ },
    "dte_type": { /* objeto dte_type completo */ },
    "next_execution": "2026-02-01T00:00:00Z"
  }
}

scheduled_document.run_succeeded

Se dispara cuando la ejecución de un documento programado es exitosa.

{
  "event": "scheduled_document.run_succeeded",
  "created_at": "2026-01-19T15:30:45.123456Z",
  "data": {
    "id": "scdo_2938475610293",
    "frequency": "monthly",
    "status": "active",
    "sender": { /* objeto sender completo */ },
    "receiver": { /* objeto receiver completo */ },
    "dte_type": { /* objeto dte_type completo */ },
    "next_execution": "2026-03-01T00:00:00Z"
  }
}

Nota: next_execution se actualiza con la próxima fecha de ejecución.

scheduled_document.run_failed

Se dispara cuando falla la ejecución de un documento programado.

{
  "event": "scheduled_document.run_failed",
  "created_at": "2026-01-19T15:30:45.123456Z",
  "data": {
    "id": "scdo_2938475610293",
    "frequency": "monthly",
    "status": "active",
    "sender": { /* objeto sender completo */ },
    "receiver": { /* objeto receiver completo */ },
    "dte_type": { /* objeto dte_type completo */ },
    "next_execution": "2026-02-01T00:00:00Z"
  }
}

Eventos de Credenciales

Estos eventos se disparan por credencial individual, incluyendo las creadas vía creación de credenciales en lote. El webhook se configura por master_entity, y una credencial puede estar asociada a más de una entidad: si eso ocurre, se envía una notificación por cada entidad que tenga un webhook suscrito al evento.

credential.validated

Se dispara cuando una credencial SII fue validada exitosamente contra el SII (login exitoso).

{
  "event": "credential.validated",
  "created_at": "2026-01-19T15:30:45.123456Z",
  "data": {
    "credential_id": "cred_7382910465728",
    "credential_type": "sii_company",
    "user": "12.345.678-5",
    "status": "VALID",
    "master_entity": {
      "id": "ment_4355019283746",
      "name": "HIDDEN CORE SPA",
      "tax_id": "78.121.555-4"
    }
  }
}

credential.invalid

Se dispara cuando una credencial SII queda inválida: clave incorrecta o cuenta bloqueada.

{
  "event": "credential.invalid",
  "created_at": "2026-01-19T15:30:45.123456Z",
  "data": {
    "credential_id": "cred_7382910465728",
    "credential_type": "sii_company",
    "user": "12.345.678-5",
    "status": "INVALID",
    "master_entity": {
      "id": "ment_4355019283746",
      "name": "HIDDEN CORE SPA",
      "tax_id": "78.121.555-4"
    }
  }
}

Nota: status refleja el estado de la credencial en Tupana (VALID / INVALID), no un detalle del error. El payload no distingue si la causa fue una clave incorrecta o una cuenta bloqueada.

Eventos Operacionales

webhook.test

Evento de prueba para verificar que tu endpoint funciona correctamente.

{
  "event": "webhook.test",
  "created_at": "2026-01-19T15:30:45.123456Z",
  "data": {
    "message": "Este es un evento de prueba de webhook",
    "webhook_id": "dowe_2c9e5a1b7f3d0",
    "timestamp": "2026-01-19T15:30:45.123456Z",
    "test": true
  }
}

Uso: Este evento se puede disparar manualmente desde la interfaz para probar tu endpoint sin esperar un evento real.

Identificadores en el payload

Cada webhook tiene un campo api_version que define el formato de todos los ids del payload:

`api_version`	`data.id`	`sender.id` / `receiver.id`	Programados, folios, prueba
2	`docu_8371029384756`	`ment_4829301923847`	`scdo_…`, `fir_…`, `dowe_…`
1 (API v1)	`1234`	`1`	enteros

Si no eliges la versión al crear, el default sigue el contexto: por /v2/webhooks/ nace en 2, por /v1/webhooks/ nace en 1, y desde la plataforma nace en la versión que ya usa la empresa (1 si tiene algún webhook con enteros, 2 si no). El selector del formulario muestra el valor preseleccionado. Los ids públicos son los mismos que devuelve la API v2, así que puedes cruzarlos directo con GET /v2/documents/ o /v2/master-entities/. Los ejemplos de esta guía muestran la versión 2.

Los webhooks creados antes de octubre de 2026 quedaron en api_version 1 para no romper integraciones que validan el id numérico. Si migraste a la API v2, súbelos a la versión 2 desde Configuración → Webhooks (selector Formato de identificadores) o con PATCH /v2/webhooks/{id}/ y el cuerpo {"api_version": 2}. Usa el botón Probar para confirmar: el webhook_id del evento webhook.test debe llegar como dowe_….

Los eventos de credenciales (credential.*) siempre traen ids públicos, en cualquier versión.

Estructura común del payload

Todos los payloads comparten esta estructura base:

event: Tipo de evento que disparó el webhook (string)
created_at: Timestamp ISO 8601 del evento (string)
data: Objeto con los datos específicos del evento (varía según el tipo)

Campos comunes en eventos de documentos

id: ID único del documento en Tupana (docu_…; entero si el webhook está en api_version 1)
folio: Folio del documento (string o null)
date_issued: Fecha de emisión en formato ISO (string)
amount_with_iva: Monto total con IVA (float)
is_sandbox: Indica si es un documento de prueba (boolean)
dte_type: Tipo de documento tributario (objeto con code y description)
sender: Información del emisor (objeto con id, name, tax_id, email)
receiver: Información del receptor (objeto con id, name, tax_id, email o null)
document_total: Totales del documento (objeto con net_amount, iva_rate, iva_amount, total_amount)
details: Array con las líneas del documento
xml_file: URL del XML del documento (string o null)
pdf_file: URL del PDF del documento (string o null, solo en document.issued)
role: Punta del documento en la que está tu empresa, "issuer" o "receiver" (string, solo en document.trace_updated)
trace: Estado de la traza del SII (objeto, solo en document.trace_updated)

Reintentos

Tupana reintenta automáticamente las entregas fallidas usando una estrategia exponencial:

Intento 1: Inmediato
Intento 2: 1 minuto después
Intento 3: 5 minutos después
Intento 4: 15 minutos después
Intento 5: 1 hora después
Intento 6: 6 horas después

Máximo de reintentos: 5 por defecto (configurable por webhook)

Idempotencia

Cada notificación tiene un delivery_id único (UUID). Si recibes el mismo delivery_id múltiples veces, es un reintento del mismo evento. Tu endpoint debe ser idempotente para evitar procesar el mismo evento varias veces.

Recomendaciones

Responde con código 2xx (200-299) para indicar éxito
Responde rápidamente (idealmente < 2 segundos)
Si tu endpoint tarda más, responde 202 Accepted y procesa asíncronamente
No proceses la misma notificación dos veces (usa delivery_id para deduplicar)

Errores comunes

Error 4xx (Client Error)

Si tu endpoint responde con un código 4xx (400-499), Tupana asume que hay un problema con la configuración o el formato de la notificación. Estos errores se reintentan, pero si persisten, considera:

Verificar que la URL es correcta y accesible
Verificar que tu endpoint acepta POST requests
Verificar que tu endpoint acepta Content-Type: application/json
Revisar los logs de tu servidor para ver el error específico

Error 5xx (Server Error)

Si tu endpoint responde con un código 5xx (500-599), Tupana asume que hay un problema temporal en tu servidor. Estos errores se reintentan automáticamente.

Timeout

Si tu endpoint no responde en 120 segundos, Tupana considera la entrega como fallida y la reintenta.

Monitoreo y Debug

Dashboard de métricas

En Configuración → Webhooks, puedes ver:

Total de entregas: Número total de notificaciones enviadas
Tasa de éxito: Porcentaje de entregas exitosas
Fallos: Número de entregas fallidas
Reintentos: Número de reintentos necesarios
Tiempo promedio de respuesta: Tiempo que tarda tu endpoint en responder
Top 5 errores: Los errores más comunes
Top 5 endpoints con fallos: URLs que más fallan

Historial de entregas

Puedes ver el historial completo de cada intento de entrega, incluyendo:

Status code recibido
Tiempo de respuesta
Mensaje de error (si falló)
Payload completo enviado

Mejores prácticas

Usa HTTPS: Tu endpoint debe usar HTTPS para seguridad
Configura un secret: Siempre configura un secret y verifica la firma
Sé idempotente: Usa delivery_id para evitar procesar el mismo evento dos veces
Responde rápido: Responde en menos de 2 segundos o usa 202 Accepted
Maneja errores: Responde con códigos HTTP apropiados
Monitorea métricas: Revisa regularmente el dashboard de métricas
Prueba primero: Usa el evento webhook.test para verificar tu endpoint

Ejemplo completo

Endpoint de ejemplo (Node.js + Express)

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

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)
  );
}

app.post('/webhooks/tupana', (req, res) => {
  // 1. Verificar firma
  const signature = req.headers['x-pana-signature'];
  if (!verifySignature(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // 2. Obtener información del evento
  const eventType = req.headers['x-pana-event-type'];
  const eventId = req.headers['x-pana-event-id'];
  const deliveryId = req.headers['x-pana-delivery'];

  // 3. Verificar idempotencia (usar delivery_id)
  if (alreadyProcessed(deliveryId)) {
    return res.status(200).json({ message: 'Already processed' });
  }

  // 4. Procesar el evento
  const { event, data } = req.body;

  switch (event) {
    case 'document.issued':
      handleDocumentIssued(data);
      break;
    case 'document.paid':
      handleDocumentPaid(data);
      break;
    case 'document.unpaid':
      handleDocumentUnpaid(data);
      break;
    // ... otros eventos
  }

  // 5. Marcar como procesado
  markAsProcessed(deliveryId);

  // 6. Responder exitosamente
  res.status(200).json({ received: true });
});

app.listen(3000, () => {
  console.log('Webhook endpoint listening on port 3000');
});

Soporte

Si tienes problemas con tus webhooks:

Revisa el Dashboard de Métricas en Configuración → Webhooks
Revisa el Historial de Entregas para ver errores específicos
Contacta a soporte con el delivery_id del intento fallido

​Webhooks

​¿Qué son los webhooks?

​Cómo crear un webhook

​Desde la interfaz web

​Ejemplo de configuración

​Seguridad

​Firma de webhooks

​Cómo verificar la firma

​Headers enviados

​Eventos soportados

​Eventos de documentos

​Eventos de documentos programados

​Eventos de credenciales

​Eventos operacionales

​Payloads por Evento

​Navegación Rápida

​Eventos de Documentos

​document.issued

​document.issue_failed

​document.updated

​document.delivered

​document.rejected

​document.paid

​document.unpaid

​document.cancelled

​document.trace_updated

Campos de trace

Códigos de evento del SII

Cuándo se envía

​Eventos de Documentos Programados

​scheduled_document.created

​scheduled_document.updated

​scheduled_document.run_started

​scheduled_document.run_succeeded

​scheduled_document.run_failed

​Eventos de Credenciales

​credential.validated

​credential.invalid

​Eventos Operacionales

​webhook.test

​Identificadores en el payload

​Estructura común del payload

​Campos comunes en eventos de documentos

​Reintentos

​Idempotencia

​Recomendaciones

​Errores comunes

​Error 4xx (Client Error)

​Error 5xx (Server Error)

​Timeout

​Monitoreo y Debug

​Dashboard de métricas

​Historial de entregas

​Mejores prácticas

​Ejemplo completo

​Endpoint de ejemplo (Node.js + Express)

​Soporte

Webhooks

¿Qué son los webhooks?

Cómo crear un webhook

Desde la interfaz web

Ejemplo de configuración

Seguridad

Firma de webhooks

Cómo verificar la firma

Headers enviados

Eventos soportados

Eventos de documentos

Eventos de documentos programados

Eventos de credenciales

Eventos operacionales

Payloads por Evento

Navegación Rápida

Eventos de Documentos

document.issued

document.issue_failed

document.updated

document.delivered

document.rejected

document.paid

document.unpaid

document.cancelled

document.trace_updated

Campos de `trace`

Eventos de Documentos Programados

scheduled_document.created

scheduled_document.updated

scheduled_document.run_started

scheduled_document.run_succeeded

scheduled_document.run_failed

Eventos de Credenciales

credential.validated

credential.invalid

Eventos Operacionales

webhook.test

Identificadores en el payload

Estructura común del payload

Campos comunes en eventos de documentos

Reintentos

Idempotencia

Recomendaciones

Errores comunes

Error 4xx (Client Error)

Error 5xx (Server Error)

Timeout

Monitoreo y Debug

Dashboard de métricas

Historial de entregas

Mejores prácticas

Ejemplo completo

Endpoint de ejemplo (Node.js + Express)

Soporte