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.
Configurarlos por API
Sección titulada «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ón | Qué hace | CLI |
|---|---|---|
obtenerConfiguracionDeWebhooks | Lee 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 |
crearConfiguracionDeWebhooks | Crea la configuración. Sin URL, sólo genera el secreto y deja el envío apagado. | redcumbre webhooks configuracion crear |
actualizarConfiguracionDeWebhooks | Cambia la URL, los eventos, los headers o el encendido. No cambia el secreto. | redcumbre webhooks configuracion actualizar --cuerpo … |
regenerarSecretoDeWebhooks | Genera 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 |
listarEntregasDeWebhooks | Lista las entregas del modo de la llave, con filtros por resultado, evento y fechas. | redcumbre webhooks entregas listar |
obtenerEntregaDeWebhook | Muestra 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úsculassecreto: 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 escucharlo imprime al abrir el relay (la línea «Verifica X-Webhook-Signature con el secreto de prueba»; sin terminal sale en el camposecretodel JSONrelay.abierto), y es el mismo con el que firmaredcumbre 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 ejemploREDCUMBRE_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 usaexpress.raw()para esa ruta.- Antigüedad: rechaza una marca
tcon 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:
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.
Eventos
Sección titulada «Eventos»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.
Catálogo
Sección titulada «Catálogo»El catálogo completo es WEBHOOK_EVENTS. Los eventos publicados, por producto:
| Producto | Eventos |
|---|---|
| Tokenización y emisores | tokenizacion.completada, emisor.certificado, emisor.revocado, emisor.actualizado, emisor.creado |
| Credencial del SII rechazada o restablecida | dte.credencial_portal_rechazada, dte.credencial_portal_restablecida, bhe.credencial_rechazada, bhe.credencial_restablecida, bhet.credencial_rechazada, bhet.credencial_restablecida |
| Boletas de honorarios | bhe.emitida, bhe.emision_terminada, bhe.pdf_sii_fallido, bhe.emision_reintentando, bhe.emision_fallida, bhe.anulada, bhe.anulacion_fallida |
| Boletas de terceros | bhet.emitida, bhet.emision_terminada, bhet.pdf_fallido, bhet.emision_reintentando, bhet.emision_fallida, bhet.anulada, bhet.anulacion_fallida |
| Documentos tributarios | dte.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 masiva | batch.completado |
| Validación masiva de RUT | validacion_rut.completada, validacion_rut.fallida |
| Verificación OTP | otp.verification-created, otp.verification-delivered, otp.verification-approved, otp.verification-failed, otp.verification-expired, otp.verification-canceled |
| PINRUT | pin.transaction.authorized, pin.transaction.failed, pin.transaction.expired, pin.transaction.cancelled, kyc.identity.level_changed |
whatsapp.mensaje.entrante, whatsapp.mensaje.eco, whatsapp.mensaje.estado, whatsapp.canal.transferido | |
| Comunicación | solicitud.creada, solicitud.resuelta, solicitud.reabierta |
| Compras y libros | compra.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.emitidodice que el documento existe (folio, timbre, XML firmado) y sale antes de que el SII responda;dte.emision_terminadadice 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 portipoDte. - Los eventos de emisión asíncrona.
*_emision_reintentandoes informativo (no reemitas);*_emision_fallidaes el desenlace definitivo y llega una sola vez.dte.emision_sin_confirmardice 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-completadoy los eventos propios de boleta por estado (dte.boleta.*), ya retirados (usadte.emision_terminaday ramifica porresultado). Seleccionarlos no da error: simplemente nunca llegan.
A dónde va cada aviso
Sección titulada «A dónde va cada aviso»- Si la operación declaró su propia URL (
webhookUrlde una sesión de tokenización,callback_urlde una transacción PINRUT,webhookUrlde una verificación OTP), el aviso va sólo a esa URL, sin mirar la lista de eventos habilitados. - 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.
- 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.
Probar los eventos desde tu computador
Sección titulada «Probar los eventos desde tu computador»El CLI recibe los eventos de prueba de la empresa y los reenvía a tu servidor local con su firma original:
redcumbre webhooks escuchar --reenviar-a http://localhost:3000/webhooks/redcumbre --eventos dte.emitido,bhe.emitidaResultado 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:
redcumbre eventos disparar dte.emitidoResultado 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.
Reintentos
Sección titulada «Reintentos»Hay dos políticas distintas y no se deben confundir:
| Reintentos de la entrega | Reintentos de la emisión | |
|---|---|---|
| Qué se reintenta | El POST a tu endpoint, cuando no respondió 2xx | La emisión del documento ante el SII, cuando éste no responde |
| Intentos | 12 | 10 |
| Espera | Se duplica desde 1 segundo, con techo de 1 minuto | Se duplica desde 5 minutos, con techo de 6 horas |
| Ventana total | Unos 6 minutos | Entre 18 y 22,6 horas |
| Qué te avisa | El 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 respuesta | Resultado |
|---|---|
2xx | Recibido |
3xx | Se reintenta, y nunca se sigue la redirección: hasta que configures la URL final, cada intento falla igual |
4xx o 5xx | Se reintenta |
| Sin respuesta en 30 segundos | Se 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:
- Responde rápido (menos de 5 segundos) con un
2xxen cuanto hayas verificado la firma y guardado el aviso; procesa después. - 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 verificarlo comprueba. - Ignora los eventos que no conozcas y responde
200. - 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.