Webhooks de Holded: cómo configurarlos y no perder avisos (2026)

01 · TL;DR

Los webhooks de Holded avisan a otro sistema en el momento en que algo pasa en tu cuenta: se aprueba una factura, se crea un contacto, cambia un pedido. En lugar de preguntar a la API cada pocos minutos si hay novedades, Holded envía un POST con el documento completo a la dirección que tú indiques. Se configuran en Configuración, apartado de desarrolladores, eligiendo eventos y acciones (crear, actualizar, borrar, aprobar). Cada envío va firmado con HMAC-SHA256 y, si tu servidor no responde con un 2xx, Holded reintenta hasta cinco veces. Las tres reglas que evitan problemas: verificar la firma sobre el cuerpo en bruto, responder rápido y procesar después, y no procesar dos veces el mismo aviso. Datos a octubre de 2026, comprobados en una cuenta real y en la documentación de Holded; es una función reciente, así que confirma los detalles en su web de desarrolladores antes de construir.

02 · Qué es un webhook y qué cambia frente a consultar la API

Hasta mediados de 2026, la única forma de enterarse de un cambio en Holded desde fuera era preguntar: cada cinco o diez minutos, un proceso pedía a la API las facturas nuevas y comparaba con lo que ya tenía. Funciona, pero tiene costes que se notan con volumen:

Aspecto	Consultar la API (polling)	Webhooks
Retraso	El intervalo de consulta, de minutos a horas	Segundos
Consumo de cuota API	Constante, haya cambios o no	Solo cuando pasa algo
Detectar cambios en documentos ya vistos	Difícil: hay que comparar versiones	Llega un evento de actualización
Qué necesitas	Un proceso programado	Una dirección HTTPS pública siempre disponible
Si tu sistema cae	Recupera en la siguiente consulta	Depende de los reintentos; pasado el último, el aviso se pierde

La última fila es la razón por la que, en integraciones serias, los webhooks no sustituyen del todo a la API: la complementan. Volvemos a ello en el punto 06. Si todavía no te has peleado con la API, empieza por la guía de la API de Holded.

03 · Cómo se configura

Prepara la dirección que recibirá los avisos. Tiene que ser HTTPS, pública y responder rápido. Un servidor propio, una función en la nube o la plataforma de automatización que uses.
Crea el webhook en Holded. En Configuración, apartado de desarrolladores, sección de webhooks. Indica la URL y elige los eventos. Cada evento se puede filtrar por acción: crear, actualizar, borrar o aprobar. También se pueden gestionar por la API v2, útil si despliegas lo mismo en varias empresas.
Guarda el secreto de firma. Holded genera un secreto que empieza por whsec_. En pantalla solo se muestra completo al crearlo; después aparece enmascarado. Guárdalo en un gestor de secretos, nunca en el código.
Suscríbete a lo mínimo. Si solo te interesan las facturas aprobadas, no actives "actualizar" en todos los documentos: recibirás un aviso por cada borrador que alguien toque.

Un aviso sobre el secreto: en nuestras pruebas, la consulta de un webhook por API devolvía el secreto completo. Trata el permiso de lectura de webhooks como si diera acceso al secreto, y no lo incluyas en claves que vayan a terceros.

04 · Qué te llega en cada aviso

Holded envía un POST con un cuerpo JSON. En las pruebas que hicimos en septiembre de 2026, el cuerpo traía el documento completo, con sus líneas y el identificador de cada una (lines[].lineId), así que en la mayoría de casos no hace falta volver a pedirlo a la API. Las cabeceras que importan son dos:

x-holded-webhook-signature: la firma, para comprobar que el aviso viene de Holded.
x-holded-webhook-id: el identificador del envío. Es tu clave para no procesar dos veces lo mismo.

05 · Verificar la firma sin errores

La firma es un HMAC-SHA256 en hexadecimal, calculado con tu secreto y precedido de sha256=. Según la documentación de desarrolladores y lo que comprobamos en real, se calcula sobre el cuerpo en bruto de la petición. En Node, la comprobación cabe en pocas líneas:

const esperado = 'sha256=' + crypto
  .createHmac('sha256', SECRETO)
  .update(cuerpoEnBruto)
  .digest('hex');
const ok = crypto.timingSafeEqual(
  Buffer.from(esperado), Buffer.from(firmaRecibida));

Los tres fallos que vemos una y otra vez:

Firmar el JSON ya interpretado. Si tu framework convierte el cuerpo en objeto y lo vuelves a serializar, un espacio o el orden de una clave cambian el resultado. Firma los bytes tal como llegaron.
Comparar con un igual normal. Usa una comparación en tiempo constante, como la del ejemplo.
Fiarse de una sola fuente. El centro de ayuda de Holded describe una variante que incluye un valor de fecha en la cadena firmada. Si tu verificación falla con todo bien configurado, revisa cuál de las dos aplica a tu cuenta con un envío de prueba.

06 · Reintentos, duplicados y avisos perdidos

Cualquier respuesta que no sea 2xx, o que tarde demasiado, cuenta como fallo, y Holded reintenta el envío hasta cinco veces. De ahí salen las reglas de diseño:

Responde primero, procesa después. Verifica la firma, guarda el aviso en una cola o una tabla y responde 200. Si haces todo el trabajo antes de responder (crear un pedido en otro sistema, mandar un correo) y tarda, Holded lo dará por fallido y te lo volverá a enviar.
Hazlo idempotente. Antes de procesar, mira si ese x-holded-webhook-id ya lo has visto. Sin esta comprobación, un reintento crea un pedido duplicado o envía dos veces el mismo correo al cliente.
No asumas orden. Una actualización puede llegar antes que la creación si la primera falló y se reintentó. Si el orden importa, decide con la fecha de modificación del documento, no con la de llegada.
Reconcilia cada noche. Si tu sistema está caído más tiempo del que cubren los reintentos, esos avisos no vuelven. Una consulta diaria a la API que compare lo de Holded con lo procesado cierra el hueco. Webhooks para la rapidez, API para la garantía.

07 · Para qué los usamos en la práctica

Evento en Holded	Acción automática	Qué se gana
Factura de venta aprobada	Registrar la venta en el CRM o en la herramienta de comisiones	Comerciales con datos del día, sin exportar Excel
Pedido de venta creado	Pasarlo al almacén o al operador logístico	Salida el mismo día, sin teclear el pedido dos veces
Presupuesto aceptado	Abrir el proyecto o la obra con sus partidas	Producción arranca con lo vendido, no con lo recordado
Contacto creado o modificado	Sincronizarlo con la herramienta de email o la tienda	Una sola ficha de cliente correcta en todas partes

Más ideas en cómo automatizar Holded y, si el sistema de destino es una tienda, en integrar Holded con WooCommerce.

08 · Webhooks y Verifactu

Con Verifactu, la acción que importa en facturas es "aprobar": es cuando el documento recibe número y Holded genera el registro de facturación. Suscríbete a la aprobación y no a la creación, porque un borrador no es una factura y puede cambiar. Y al revés: un webhook nunca debe intentar corregir una factura aprobada, porque ya no se edita, se rectifica. El calendario legal vigente es el del RD-ley 15/2025: obligatorio desde el 1 de enero de 2027 para sociedades y desde el 1 de julio de 2027 para autónomos; en 2026 es voluntario. El 5 de octubre de 2026 Hacienda anunció su intención de aplazarlo a octubre de 2028, pero a la fecha de este artículo no hay norma publicada en el BOE que lo haga. Detalles en Holded y Verifactu.

09 · Cuándo no merece la pena

Si lo que necesitas es un informe semanal o una sincronización que puede esperar a la noche, una consulta programada a la API es más simple y no exige mantener una dirección pública. Los webhooks compensan cuando el retraso cuesta dinero (pedidos, stock, cobros) o cuando el volumen hace que consultar cada pocos minutos se coma la cuota. En los proyectos que montamos, la combinación habitual es webhook para lo urgente y reconciliación diaria por API, con avisos a una persona solo cuando algo no cuadra.

Como partner de Holded, diseñamos estas integraciones con firma verificada, control de duplicados y reconciliación, para que nadie tenga que vigilar si llegó el aviso. Habla con un partner de Holded →

10 · Preguntas frecuentes

¿Holded tiene webhooks?

Sí. Desde mediados de 2026 Holded permite crear webhooks en Configuración, apartado de desarrolladores, y también por la API v2. Se eligen eventos y acciones (crear, actualizar, borrar, aprobar) y Holded envía un POST con el documento a la URL indicada.

¿Cómo se verifica la firma de un webhook de Holded?

Cada envío incluye la cabecera x-holded-webhook-signature con un HMAC-SHA256 en hexadecimal, precedido de sha256=, calculado con el secreto del webhook sobre el cuerpo en bruto de la petición. Hay que compararlo en tiempo constante.

¿Qué pasa si mi servidor no responde a un webhook de Holded?

Si la respuesta no es 2xx o tarda demasiado, Holded reintenta hasta cinco veces. Pasado el último intento el aviso no vuelve, por eso conviene una reconciliación diaria por API.

¿Cómo evito procesar dos veces el mismo webhook?

Guarda el valor de la cabecera x-holded-webhook-id de cada aviso procesado y descarta los que ya hayas visto. Responde 200 enseguida y procesa en segundo plano.

¿Quieres que Holded avise a tus otros sistemas sin duplicados ni avisos perdidos? Lo diseñamos contigo. Solicitar diagnóstico →

Webhooks de Holded: cómo configurarlos y no perder avisos.