Adelys Docs

Biblioteca › Portales e integraciones › Webhooks y API

Webhooks y API: sacar los eventos del CRM

Al terminar vas a tener tus sistemas recibiendo, firmados, los eventos de tu CRM —una cotización ganada, un lead convertido, lo que tú decidas nombrar—, y vas a saber verificar la firma y leer el registro de entregas cuando algo no llegue.

Módulo: Conexiones Seguras → Webhooks salientes Desde el plan: Pro Solo administrador ⏱ 15 min

Antes de empezar

Paso a paso

Míralo hecho. Los pasos de este tutorial, tal cual en el CRM: el cursor hace cada clic donde se hizo de verdad. Pulsa el número de un paso para ir a su cuadro.

crm.adelys.app/conexiones
Cargando el flujo…
1

Baja hasta Webhooks salientes

Conexiones Seguras, y al final de la página —debajo de la biblioteca de integraciones— la sección WEBHOOKS SALIENTES. La descripción resume lo que hace: «Envía cada evento del CRM (cliente creado, cotización ganada, servicio iniciado…) a tus sistemas, firmado HMAC».

De paso, fíjate en la tarjeta de Zapier del catálogo: dice Webhook entrante. Ese conector todavía no está construido; lo que sí funciona y hace el mismo trabajo es lo que estás a punto de configurar — Zapier, Make o n8n reciben perfectamente un POST firmado.

Parte inferior de Conexiones Seguras: el buscador de la biblioteca filtrado por «zapier» mostrando una sola tarjeta de Zapier con las etiquetas Automatización, Seguridad Medio y Webhook entrante, y debajo la sección WEBHOOKS SALIENTES con su tarjeta y el texto «Disponible al conectar el backend. Envía cada evento del CRM (cliente creado, cotización ganada, servicio iniciado…) a tus sistemas, firmado HMAC»
La leyenda «Disponible al conectar el backend» es de la demostración pública, que corre sin servidor. En tu cuenta ahí va la lista de tus webhooks con su botón Nuevo.
2

Crea la suscripción y guarda el secreto en ese momento

Pulsa Nuevo y llena tres campos:

  • URL — http o https, la tuya.
  • Tipos de evento — separados por comas. Acepta comodines: * es todo, y cotizacion.* es todo lo que empiece por ahí. Vacío equivale a todo.
  • Descripción — para acordarte dentro de seis meses de qué sistema es ese.

Al crear, la pantalla te muestra el secreto de firma (empieza por whsec_) una sola vez, con un botón para copiarlo. Cópialo ahora y guárdalo donde guardes las credenciales: no hay «ver secreto». Si lo pierdes, la salida es Regenerar secreto, y eso invalida el anterior.

3

Prepara tu receptor: qué llega y cómo se verifica

Cada evento llega como un POST con el cuerpo en JSON:

  • id, type, module, recordId, clientId, payload y at.

Y con cuatro cabeceras propias: X-Adelys-Event (el tipo), X-Adelys-Timestamp, X-Adelys-Nonce y X-Adelys-Signature.

La firma se calcula como HMAC-SHA256 sobre la cadena timestamp + "." + nonce + "." + cuerpo, usando tu secreto, y viaja en formato sha256=<hex>. Tres reglas para no equivocarte al verificar:

  • Firma sobre el cuerpo crudo, tal como llegó — no sobre el JSON que tu framework volvió a serializar.
  • Compara en tiempo constante, no con ==.
  • Rechaza lo viejo y lo repetido: el timestamp y el nonce están para eso, y la deduplicación es responsabilidad de tu receptor.

Responde 2xx y rápido: el CRM corta la espera a los 8 segundos.

4

Prueba, y aprende a leer las entregas

Cada webhook de la lista trae cuatro controles: Activo / Pausado, Enviar prueba, Ver entregas y Regenerar secreto, más eliminar.

Enviar prueba manda un evento webhook.test ahora mismo y te dice si tu servidor lo aceptó. Ver entregas despliega las últimas con su estado —delivered, failed, pending—, el número de intentos y el último error.

Si tu servidor no contesta, el CRM no se rinde a la primera: reintenta hasta seis veces, espaciando cada vez más (30 s, 1 min, 2 min, 4 min… hasta un tope de una hora). Un despliegue tuyo de diez minutos no pierde eventos.

5

Elige los eventos que existen hoy

El CRM publica por su cuenta un conjunto pequeño y bien definido:

  • cotizacion.ganada — con el número y el total.
  • cotizacion.convertida.* — al convertir una cotización, con su destino.
  • lead.convertido — con el cliente y la oportunidad creados.
  • oportunidad.cotizada — con el número de la cotización.
  • servicio.iniciado — con el servicio del catálogo.

Cortos a propósito: son eventos de negocio, no un volcado de cada tecla. Para todo lo demás está el paso siguiente.

6

Convierte cualquier flujo en un evento tuyo

Esta es la parte que la mayoría no encuentra, y es la que hace útil todo lo anterior. En Automatizaciones, entre las acciones hay una de categoría integración: «Avisar a un sistema externo (webhook)». Su descripción lo dice entero: «Publica un evento firmado HMAC hacia las suscripciones de webhook del tenant. Convierte cualquier flujo en integrable con lo que sea, sin escribir un conector».

Le pones el nombre del evento que quieras —por ejemplo crm.compra.solicitada— y una nota, y ese nombre es el que vas a poder filtrar en tu suscripción. Así, cualquier disparador del CRM (un stock bajo, un cambio de estado, una fecha que llega) termina en tu sistema.

El paso es honesto cuando no puede cumplir: sin sesión con servidor te responde «Evento no publicado: requiere sesión con backend» en vez de decir que salió.

7

Y en el otro sentido: el único webhook entrante que existe

Para que algo entre al CRM en tiempo real hay hoy un solo camino construido, el de WordPress / WooCommerce con Digitalek Admin. Está en Pedidos → Conexión WooCommerce, en el bloque Webhook en tiempo real — configuración en WordPress: te da la dirección exacta a la que apuntar (lleva el identificador de tu organización) y las reglas.

Los eventos llegan firmados con X-DKA-Signature: sha256=<hmac> usando el secreto que configuraste; una firma inválida se rechaza. Si el webhook falla, el módulo tiene un respaldo: consulta periódicamente los pedidos nuevos mientras tienes la pestaña a la vista.

Pestaña Conexión WooCommerce del módulo Pedidos: el estado vacío que pide conectar un WordPress con Digitalek Admin v2.1.0+, el bloque «Mapeo de estados WooCommerce → Adelys» y el bloque «Webhook en tiempo real — configuración en WordPress» con la dirección a la que apuntar y la explicación de la firma X-DKA-Signature, el drenado cada 15 s y el token cifrado AES-256-GCM
La dirección incluye el identificador de tu organización: cada tenant tiene la suya y un evento no puede caer en el CRM de otro.
No hay todavía una API pública con llaves para terceros. La API de Adelys existe y es la que usa el propio CRM, pero se autentica con la sesión del usuario: no se emiten llaves de API por organización para que un sistema ajeno consulte tus datos. Lo que sí puedes hacer hoy, y sin esperar a nada, es lo de esta página: que el CRM empuje sus eventos hacia ti, firmados. Si lo que necesitas es leer en frío, la salida es la exportación — ver Tus datos son tuyos.
Direcciones internas: rechazadas. Antes de guardar una URL y antes de cada entrega, el servidor comprueba a dónde apunta de verdad y descarta las direcciones privadas, de bucle local y de metadatos de la nube — y vuelve a comprobarlo salto a salto si hay redirecciones. Es lo que impide que un webhook se use para hacer que el servidor de Adelys toque su propia red. Si tu receptor está en una red interna, exponlo por un túnel o una dirección pública.
Tip: el secreto es por suscripción, no por cuenta. Un webhook por sistema receptor —uno para tu ERP, otro para Make, otro para el bot de Slack— te deja pausar o rotar uno sin tocar los demás, y el registro de entregas te dice cuál de los tres es el que está fallando.

Casos prácticos

Ferretería El Tornillo — la reposición que avisa al proveedor

Cuando un producto baja del mínimo, una automatización del CRM dispara la acción Avisar a un sistema externo (webhook) con el evento crm.compra.solicitada y una nota con el nombre del producto. En Conexiones Seguras hay una suscripción apuntando a un escenario de Make, filtrada por crm.compra.*, que verifica la firma y arma el correo de pedido al proveedor. Nadie escribió un conector: se conectaron dos cosas que ya existían.

Estudio Contable Vista Alegre — la cotización ganada que abre el expediente

El estudio lleva sus carpetas en un sistema propio. Suscriben una sola URL a cotizacion.ganada. Cada vez que se gana una, su sistema recibe el número, el total y el clientId, verifica X-Adelys-Signature sobre el cuerpo crudo y abre la carpeta del trabajo. La primera semana un despliegue les tumbó el receptor media hora: al volver, las entregas pendientes habían entrado solas por los reintentos, y en Ver entregas quedó el rastro de los intentos fallidos.

Preguntas frecuentes

¿Puedo recuperar el secreto si lo perdí?

No, y es la propiedad, no una limitación: el secreto se guarda cifrado y no existe una pantalla que lo devuelva. Usa Regenerar secreto, actualiza tu receptor y listo. El anterior deja de firmar en ese momento.

Mi servidor tardó en responder y el evento se marcó como fallido.

El límite de espera es de 8 segundos. La forma correcta de recibir un webhook es contestar 2xx enseguida y procesar después, en tu propia cola. Si tardas en contestar porque estás trabajando, vas a fallar entregas que en realidad procesaste.

¿Puede llegarme el mismo evento dos veces?

Puede, y tienes que estar preparado: por eso cada entrega lleva id y X-Adelys-Nonce. Guarda los identificadores que ya procesaste y descarta los repetidos. Es la regla estándar de cualquier receptor de webhooks.

¿Los webhooks de un cliente pueden recibir eventos de otro?

No. Cada suscripción pertenece a una organización y solo recibe los eventos de esa organización, tanto al encolar como al entregar. Crear y eliminar suscripciones queda además registrado en la auditoría, porque un webhook es, por definición, una salida de datos.

¿Hay un límite de peticiones?

Sí, hay cupos por organización y por dirección de origen para todo lo que toca la API. No suelen notarse en el uso normal; el detalle está en Límites y cupos.

Sigue con