Ir al contenido

Webhooks

Un webhook es un POST con JSON que REDCUMBRE envía a tu servidor cuando algo ocurre (un documento emitido, un emisor autorizado, una verificación terminada). En vez de consultar la API cada tanto, tu servidor se entera solo. Lo usan casi todas las fichas.

Trata el webhook como un aviso, no como la fuente de verdad: puede perderse (ver Reintentos). El estado vigente siempre está en la API; para flujos críticos, reconcilia periódicamente lo que quedó sin desenlace.

Dónde se configura: por API con la llave del proyecto, o en el panel (General → Webhooks, en Prueba o en Producción). Es la misma configuración y cada modo tiene la suya: su secreto de firma, sus headers y su URL por defecto. Un aviso de prueba nunca se firma con el secreto de producción, ni al revés. La llave configura el modo al que pertenece (la de prueba, el de prueba; la de producción, el de producción); ver Configurarlos por API.

La configuración de los webhooks de la empresa se administra con la llave del proyecto, sin pasar por el panel. En el CLI es redcumbre webhooks configuracion … y redcumbre webhooks entregas ….

OperaciónQué haceCLI
obtenerConfiguracionDeWebhooksLee la configuración: URL, eventos, headers, si está activa y si el secreto ya está configurado. Responde null si todavía no existe. Nunca devuelve el secreto.redcumbre webhooks configuracion ver
crearConfiguracionDeWebhooksCrea la configuración. Sin URL, sólo genera el secreto y deja el envío apagado.redcumbre webhooks configuracion crear
actualizarConfiguracionDeWebhooksCambia la URL, los eventos, los headers o el encendido. No cambia el secreto.redcumbre webhooks configuracion actualizar --cuerpo …
regenerarSecretoDeWebhooksGenera un secreto nuevo. Con anterior eliges si el viejo vence ahora (vencer-ahora, el valor por omisión) o sigue firmando hasta 24 horas (mantener-24h).redcumbre webhooks configuracion regenerar-secreto
listarEntregasDeWebhooksLista las entregas del modo de la llave, con filtros por resultado, evento y fechas.redcumbre webhooks entregas listar
obtenerEntregaDeWebhookMuestra una entrega con sus intentos.redcumbre webhooks entregas ver <id>

El secreto sale una sola vez. crearConfiguracionDeWebhooks y regenerarSecretoDeWebhooks lo devuelven en el campo secretoNuevo; ninguna otra operación lo entrega, ni obtenerConfiguracionDeWebhooks. Guárdalo en ese momento en la variable de entorno de tu receptor: si lo pierdes, regenera uno. El CLI lo imprime con el aviso «Guárdalo: no se vuelve a mostrar». No lo escribas en un archivo del proyecto ni lo repitas en un mensaje.

Ninguna de las seis envía un aviso a un tercero; probar tu receptor sigue siendo del modo de prueba.

Todo webhook va firmado con HMAC-SHA256, a cualquier destino. Tu receptor tiene que verificar la firma antes de procesar nada: sin ella cualquiera podría llamar a tu URL.

El header es X-Webhook-Signature y no trae el digest a secas, sino el esquema con marca de tiempo:

X-Webhook-Signature: t=<unix_timestamp>,v1=<hmac_hex>

Mientras dura una rotación del secreto (hasta 24 horas, si quien administra la dejó así) trae dos v1, una por secreto, con el mismo t. Acepta el aviso si cualquiera coincide.

Cómo se calcula:

firma = HMAC_SHA256(secreto, "<t>.<cuerpo>") → hexadecimal en minúsculas
  • secreto: 64 caracteres hexadecimales, el de ese modo (prueba o producción). En el modo de prueba no necesitas el panel ni a la persona: redcumbre webhooks escuchar lo imprime al abrir el relay (la línea «Verifica X-Webhook-Signature con el secreto de prueba»; sin terminal sale en el campo secreto del JSON relay.abierto), y es el mismo con el que firma redcumbre prueba verificar. El de producción sale una sola vez al crear la configuración o al regenerar el secreto, por API con la llave de producción o en el panel; si no lo guardaste, regenera uno. Guárdalo en una variable de entorno de tu receptor (por ejemplo REDCUMBRE_WEBHOOK_SECRET); no lo escribas en un archivo del proyecto, no lo subas al repositorio y no lo repitas en un mensaje.
  • cuerpo: el cuerpo tal cual llegó por la red. Si tu framework lo convierte en objeto y luego lo vuelves a serializar, el orden de las claves o los espacios cambian y la firma nunca coincide. En Express usa express.raw() para esa ruta.
  • Antigüedad: rechaza una marca t con más de unos 5 minutos de diferencia respecto de tu reloj, para impedir que se reutilice un aviso capturado.
  • Comparación: en tiempo constante, y comparando antes el largo de los dos valores.
const crypto = require('crypto');
function validarFirma(rawBody, header, secreto) {
if (!header) return false;
let t;
const firmas = [];
for (const parte of header.split(',')) {
const i = parte.indexOf('=');
const clave = parte.slice(0, i);
const valor = parte.slice(i + 1);
if (clave === 't') t = valor;
if (clave === 'v1') firmas.push(valor);
}
if (!t || firmas.length === 0) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - Number(t)) > 300) return false;
const esperada = crypto.createHmac('sha256', secreto).update(`${t}.${rawBody}`).digest();
return firmas.some((v1) => {
const recibida = Buffer.from(v1, 'hex');
return recibida.length === esperada.length && crypto.timingSafeEqual(recibida, esperada);
});
}

Resultado esperado: true para un aviso genuino con el secreto correcto; false si se alteró el cuerpo, si el secreto es de otro modo o si el aviso es viejo. Si la firma no coincide, responde 401 y no proceses el aviso.

Si REDCUMBRE no puede calcular la firma (por ejemplo, no hay secreto), el aviso no sale y queda como fallido en el historial de entregas.

Verificación contra tu propio servidor. Para comprobar que tu receptor valida la firma, ignora un aviso alterado y no repite el efecto de una entrega duplicada, usa el CLI en el modo de prueba:

Ventana de terminal
redcumbre prueba verificar --reenviar-a http://localhost:3000/webhooks/redcumbre --efectos "<tu comando que imprime cuántas veces se aplicó el efecto>"

Resultado esperado: «✓ Tu sitio recibe los webhooks, valida la firma y no repite el efecto» con la cantidad de eventos comprobados; si algo falla, el comando termina con error y dice qué comprobación no pasó.

Antes de correrlo, tu receptor tiene que estar escuchando en esa URL con el secreto de prueba (sin él no puede validar la firma y el comando lo reporta: NO_VALIDA_FIRMA si acepta un aviso alterado, DESTINO_RECHAZA si no responde). El secreto sale de redcumbre webhooks escuchar (ver Firma): ábrelo, copia el valor a la variable de entorno de tu receptor, ciérralo con Ctrl+C y levanta el receptor. Sin --eventos verifica todos los eventos que se pueden disparar en prueba (los de boletas, documentos, guías, lotes, compras y libros), así que tu receptor responde 200 a los que no usa; con --eventos bhe.emitida,bhe.anulada verifica sólo los que le importan a tu integración. Un evento que no se puede disparar en prueba no cuenta como verificado ni como fallido.

El POST lleva un campo event con el nombre del evento. Ramifica por event e ignora los que no reconozcas, respondiendo 200: la plataforma suma eventos con el tiempo y un error ante uno desconocido sólo dispara reintentos inútiles.

Ejemplo del aviso de un emisor autorizado (el resto de los eventos tiene su propia forma, con los datos de su recurso):

{
"event": "tokenizacion.completada",
"tenantId": "8",
"sessionId": "c6c53392-bdb0-4053-8b9d-5b34296d63a3",
"code": "83aK0esV0V21u8-krvuMiXx1OqheSVy56E6tBG3OjX8",
"emisorId": "cmikf6ei00001sek0mxzcf668",
"rut": "12345678-5",
"tipoAutenticacion": "CLAVE_TRIBUTARIA",
"tipoEmisor": "tributario",
"sandbox": true,
"timestamp": "2026-11-05T14:30:00Z"
}

Todo aviso lleva sandbox: true si ocurrió en modo de prueba, false si en producción.

El catálogo completo es WEBHOOK_EVENTS. Los eventos publicados, por producto:

ProductoEventos
Tokenización y emisorestokenizacion.completada, emisor.certificado, emisor.revocado, emisor.actualizado, emisor.creado
Credencial del SII rechazada o restablecidadte.credencial_portal_rechazada, dte.credencial_portal_restablecida, bhe.credencial_rechazada, bhe.credencial_restablecida, bhet.credencial_rechazada, bhet.credencial_restablecida
Boletas de honorariosbhe.emitida, bhe.emision_terminada, bhe.pdf_sii_fallido, bhe.emision_reintentando, bhe.emision_fallida, bhe.anulada, bhe.anulacion_fallida
Boletas de tercerosbhet.emitida, bhet.emision_terminada, bhet.pdf_fallido, bhet.emision_reintentando, bhet.emision_fallida, bhet.anulada, bhet.anulacion_fallida
Documentos tributariosdte.emitido, dte.emision_terminada, dte.emision_sin_confirmar, dte.emision_reintentando, dte.emision_fallida, dte.acuse_reclamado, dte.acuse_aceptado, dte.guia_anulada, dte.guia_modificada
Carga masivabatch.completado
Validación masiva de RUTvalidacion_rut.completada, validacion_rut.fallida
Verificación OTPotp.verification-created, otp.verification-delivered, otp.verification-approved, otp.verification-failed, otp.verification-expired, otp.verification-canceled
PINRUTpin.transaction.authorized, pin.transaction.failed, pin.transaction.expired, pin.transaction.cancelled, kyc.identity.level_changed
WhatsAppwhatsapp.mensaje.entrante, whatsapp.mensaje.eco, whatsapp.mensaje.estado, whatsapp.canal.transferido
Comunicaciónsolicitud.creada, solicitud.resuelta, solicitud.reabierta
Compras y libroscompra.documento_recibido, compra.acuse_resuelto, compra.acuse_fallido, libro.sincronizado, libro.sincronizacion_fallida

Para ver el catálogo vigente y cuáles se pueden disparar en prueba: redcumbre eventos (operación listarEventosDeWebhookModoPrueba).

Tres puntos que importan al diseñar:

  • Emitir y que el SII lo dé por bueno son dos hitos distintos. dte.emitido dice que el documento existe (folio, timbre, XML firmado) y sale antes de que el SII responda; dte.emision_terminada dice que el SII lo resolvió (aceptado, con reparos o rechazado) y sale una sola vez por documento. Entrégale el documento a tu receptor con el segundo, aceptado. No hay eventos propios de boleta ni de nota: pasan por los mismos dos hitos y ramificas por tipoDte.
  • Los eventos de emisión asíncrona. *_emision_reintentando es informativo (no reemitas); *_emision_fallida es el desenlace definitivo y llega una sola vez. dte.emision_sin_confirmar dice que la plataforma no pudo confirmar el resultado; no afirma rechazo ni pérdida.
  • No diseñes contra eventos que no se despachan. El panel deja seleccionar algunos que hoy no llegan a ningún endpoint: onexo.*, validafirma.documento-completado y los eventos propios de boleta por estado (dte.boleta.*), ya retirados (usa dte.emision_terminada y ramifica por resultado). Seleccionarlos no da error: simplemente nunca llegan.
  1. Si la operación declaró su propia URL (webhookUrl de una sesión de tokenización, callback_url de una transacción PINRUT, webhookUrl de una verificación OTP), el aviso va sólo a esa URL, sin mirar la lista de eventos habilitados.
  2. Si no declaró ninguna, va a la URL por defecto de la empresa, siempre que exista, que «Enviar a esta URL» esté encendido y que la lista de eventos habilitados lo deje pasar.
  3. Si no hay a dónde enviarlo, no se envía y queda como «no enviada» en el historial. En prueba nunca se desvía a la URL de producción.

Una lista de eventos habilitados vacía significa «todos», salvo ocho que exigen selección explícita por su volumen: dte.emitido, dte.emision_terminada, dte.emision_sin_confirmar, dte.acuse_reclamado, dte.acuse_aceptado, batch.completado, emisor.actualizado y emisor.creado. Si emites documentos y no ves llegar nada, revisa eso primero.

El CLI recibe los eventos de prueba de la empresa y los reenvía a tu servidor local con su firma original:

Ventana de terminal
redcumbre webhooks escuchar --reenviar-a http://localhost:3000/webhooks/redcumbre --eventos dte.emitido,bhe.emitida

Resultado esperado: «Relay abierto en el modo de prueba», el secreto de prueba para verificar X-Webhook-Signature y, por cada entrega, una línea con el evento, el código con que respondió tu servidor y la duración. Ctrl+C lo cierra. Usa la sesión de un administrador de la empresa (redcumbre login) y solo opera en el modo de prueba.

Para provocar un evento sin esperar a que ocurra:

Ventana de terminal
redcumbre eventos disparar dte.emitido

Resultado esperado: la API responde 202 con el evento y la referencia del recurso de prueba que lo originó, y el aviso llega a tu destino de prueba o al relay abierto.

{
"evento": "dte.emitido",
"referencia": "dte_ejemplo123",
"sandbox": true
}

El evento nace de ejecutar de verdad, en prueba, la operación que lo produce, así que deja un documento de prueba en el panel. Con una llave de producción responde 409 y no crea nada; un evento fuera del catálogo responde 404, y uno que no se puede disparar en prueba, 422 con el motivo. redcumbre estado muestra el modo de la llave y consultarEstadoModoPrueba dice si el destino de webhooks de prueba está configurado y cuántos relays hay abiertos.

Hay dos políticas distintas y no se deben confundir:

Reintentos de la entregaReintentos de la emisión
Qué se reintentaEl POST a tu endpoint, cuando no respondió 2xxLa emisión del documento ante el SII, cuando éste no responde
Intentos1210
EsperaSe duplica desde 1 segundo, con techo de 1 minutoSe duplica desde 5 minutos, con techo de 6 horas
Ventana totalUnos 6 minutosEntre 18 y 22,6 horas
Qué te avisaEl historial de entregas; al agotarse, un correo a los SUPER-ADMIN*_emision_reintentando y, al final, *_emision_fallida

Una emisión puede reintentarse durante horas y, aun así, perderse el aviso si tu endpoint estuvo caído justo cuando se intentó entregar.

Qué cuenta como entrega correcta:

Tu respuestaResultado
2xxRecibido
3xxSe reintenta, y nunca se sigue la redirección: hasta que configures la URL final, cada intento falla igual
4xx o 5xxSe reintenta
Sin respuesta en 30 segundosSe reintenta

Al agotarse los 12 intentos, el aviso se pierde. No hay reenvío ni forma de pedirlo de nuevo. El historial de entregas (30 días, en General → Webhooks) muestra qué se perdió, pero no guarda el contenido. Un endpoint que estuvo caído más de unos 6 minutos pierde todo lo que se le intentó entregar en ese lapso. De ahí la regla del inicio: reconcilia con la API.

Cómo diseñar tu receptor:

  1. Responde rápido (menos de 5 segundos) con un 2xx en cuanto hayas verificado la firma y guardado el aviso; procesa después.
  2. Sé idempotente: los reintentos pueden entregar el mismo aviso más de una vez. Detecta duplicados con el evento y el identificador del recurso que trae su cuerpo, y aplica el efecto una sola vez. El comando redcumbre prueba verificar lo comprueba.
  3. Ignora los eventos que no conozcas y responde 200.
  4. Reconcilia: consulta periódicamente los recursos que quedaron sin desenlace (por ejemplo, un intento de emisión) en vez de depender sólo del aviso.