Un webhook en Bitrix24 (Alaio) es la forma de conectar el portal con un servicio externo sin escribir una aplicación: el webhook entrante da al sistema externo una URL-clave para llamar a la API REST del portal; el saliente hace que Bitrix24 mismo llame a tu URL cuando ocurre un evento. Es la vía de integración más rápida, pero tiene límites de los que la ayuda no habla. Veamos ambos tipos, su creación, sus limitaciones y el tercer escenario, que es el que más a menudo hace falta: el webhook desde un proceso de negocio.

¿En qué se diferencia un webhook entrante de uno saliente?

El entrante es una URL del tipo https://portal.bitrix24.com/rest/1/clave/, mediante la cual un servicio externo llama a métodos de la API REST: crear un prospecto, actualizar una negociación, obtener la lista de tareas. Los permisos se fijan al crearlo (solo CRM, solo tareas, etc.) y las acciones se ejecutan en nombre del empleado dueño de la clave. El saliente es al revés: tú indicas la URL de tu manejador y un evento (prospecto creado, negociación actualizada), y Bitrix24 envía allí un POST en cada activación. La combinación de ambos tipos da una integración bidireccional: el saliente avisa «apareció un contacto», el servicio externo enriquece los datos y, con un webhook entrante, los escribe de vuelta.

¿Dónde crear un webhook y qué comprobar?

Sección «Para desarrolladores» (en los menús antiguos, «Aplicaciones») → «Otro» → «Webhook entrante» / «Webhook saliente». Para el entrante: elige los permisos al mínimo; una clave con permisos «CRM + todo lo demás», en caso de fuga, entrega al atacante toda la base; copia la URL con la clave y guárdala como una contraseña. Para el saliente: indica la URL del manejador y el token de la aplicación para verificar la autenticidad; el manejador está obligado a comprobar el token, de lo contrario cualquiera que averigüe la dirección podrá enviar eventos falsos. La disponibilidad de los webhooks depende de la tarifa: en parte de las tarifas se necesita una suscripción a Bitrix24 Market.

¿Qué limitaciones tienen los webhooks?

Tres, contra las que chocan las integraciones. Límite de peticiones: la API REST admite aproximadamente dos peticiones por segundo por portal; al superarlo, error QUERY_LIMIT_EXCEEDED; las operaciones masivas se empaquetan en llamadas batch. El webhook saliente no reintenta la entrega: si tu manejador estuvo inaccesible tres segundos, el evento se pierde; Bitrix24 no reintenta. Y el webhook saliente lleva un mínimo de datos (ID y tipo de evento): por los campos hay que ir igualmente con un webhook entrante a la API REST. Por eso «un bus fiable basado en webhooks salientes» es un mito: para los eventos críticos hace falta una entrega con confirmación y reintentos.

¿Cómo enviar un webhook desde un proceso de negocio?

Escenario frecuente que no está entre las acciones estándar: al pasar la negociación a una etapa, llamar a un servicio externo: un sistema de gestión, un almacén, un bot de mensajería. Esto lo cubren dos robots de Roboteka. «Solicitud HTTP» envía un GET o POST con cabeceras y cuerpo, y devuelve la respuesta y el código de estado a variables del proceso, para escenarios síncronos de «pregunté y obtuve respuesta» (la respuesta la analiza el robot «Extraer valor de un JSON por ruta»). «Webhook tolerante a fallos» es para el escenario «entregar sí o sí»: reintenta el envío cuando el receptor no está disponible, y el evento no se pierde mientras el servicio externo se reinicia. Regla de elección: ¿hace falta una respuesta aquí y ahora? Solicitud HTTP; ¿hace falta garantía de entrega de una notificación? Webhook tolerante a fallos.

¿Quién puede crear webhooks y se puede restringir?

Cualquier empleado que tenga acceso a la sección de recursos para desarrolladores, no solo los administradores. El módulo REST reserva a los administradores solo algunas plantillas de integración ya hechas, como las que añaden un widget a la ficha del CRM. Un webhook entrante o saliente normal lo puede crear un empleado por su cuenta, y funciona con los permisos de ese empleado. No existe un interruptor del tipo «webhooks solo para administradores». Por eso conviene que el administrador revise la lista de webhooks de vez en cuando (en la siguiente sección se explica dónde está). Además, bloquear la creación no resuelve el riesgo principal: un webhook creado por un empleado ve en el CRM exactamente lo mismo que ve ese empleado.

¿Dónde ver los webhooks existentes y cómo eliminar uno?

Abre la sección de recursos para desarrolladores y entra en la lista de integraciones. Un empleado ve solo sus propios webhooks; el administrador los ve todos y puede filtrar por autor. La clave (la parte secreta de la URL) solo la ve su autor: si el administrador abre el webhook de otra persona, ve asteriscos en lugar del código. Si hay una integración funcionando y nadie recuerda quién la montó, búscala en esta lista por autor y fecha, no por URL. El webhook se elimina desde el menú de la fila en la lista. A partir de ese momento el sistema externo empieza a recibir errores de autorización, así que antes averigua quién usa la clave. Revisa aparte los webhooks de empleados que ya no están en la empresa; qué pasa con ellos cuando alguien se va lo explicamos en la guía de baja de empleados.

¿Se puede crear un webhook de solo lectura?

Un webhook entrante no tiene una casilla de «solo lectura». Los permisos se eligen por módulo al crear el webhook (CRM, tareas, usuarios, etc.), y dentro de un módulo el webhook puede leer y también escribir. La única forma de limitarlo es a través de los derechos del usuario en cuyo nombre funciona: el webhook hace cada petición en nombre de su autor y está sujeto a su rol. De ahí sale una solución práctica. Crea un usuario dedicado a la integración, asígnale un rol del CRM con acceso de solo lectura a las entidades que necesitas y crea el webhook con ese usuario. Si la clave se filtra, con ella no se puede cambiar ni borrar nada. Ten en cuenta que este usuario ocupa una plaza del límite de usuarios de tu plan. Como ventaja añadida, la integración deja de depender de un responsable concreto: cuando esa persona se va, el intercambio de datos sigue funcionando.

¿Qué le doy a un contratista que nos va a enviar prospectos?

Normalmente piden «una URL o un webhook», y las dos cosas son lo mismo: la dirección de un webhook entrante al que su sistema llamará con crm.lead.add. Genera una clave solo con el módulo CRM, creada con el usuario de integración de la sección anterior, no con tu propia cuenta de administrador. La dirección funciona como una contraseña: quien la tenga puede escribir en tu CRM. Si dejas de trabajar con el contratista, elimina el webhook en la lista de integraciones y el acceso se corta en el acto. Si el contratista solo necesita enviar solicitudes desde un sitio web, es más sencillo un formulario del CRM: así no hace falta ninguna clave de la API REST.

El robot «Webhook saliente»: ¿qué se pone en el campo «Handler»?

Bitrix24 tiene un robot estándar llamado «Webhook saliente». Tiene un solo campo, «Handler», donde se indica la dirección de tu servicio: http o https, con nombre de dominio. El robot envía allí una petición con el identificador del documento (document_id, por ejemplo la negociación DEAL_10) y sigue adelante en el acto. No espera respuesta ni devuelve nada al proceso de negocio. Tampoco envía los campos de la negociación. Los valores que necesites añádelos a la dirección como parámetros: https://example.com/hook?deal={=Document:ID}&sum={=Document:OPPORTUNITY}. Otra particularidad: si tu plan no incluye REST, el robot no hace nada y en el registro no aparece ningún error. Cuando necesites una cabecera de autorización, un cuerpo JSON o la respuesta del servicio en una variable del proceso, usa «Solicitud HTTP». Cuando el evento no se puede perder, usa «Webhook tolerante a fallos»: reintenta según un calendario, hasta diez intentos.

El webhook no funciona: lista de verificación

El entrante devuelve error: comprueba los permisos de la clave (el método requiere un alcance que no tiene), la actividad del empleado dueño (un empleado despedido = clave muerta) y el límite de peticiones. El saliente no llega: comprueba que el manejador responde con código 200 rápido (Bitrix24 considera error una respuesta lenta), que la URL es accesible desde fuera (no es localhost, no está bloqueada por el cortafuegos) y que el evento es realmente el que crees: «actualización de negociación» no se activa al cambiar de etapa en el kanban de tareas. Y recuerda la ausencia de reintentos: si el receptor estuvo caído, el evento hay que recuperarlo a mano, o enviarlo desde el inicio mediante el webhook tolerante a fallos desde el proceso.

Conclusión

Los webhooks son la forma más barata de integración con Bitrix24: el entrante para gestionar el portal desde fuera, el saliente para señales hacia fuera y, desde los procesos de negocio, robots con solicitud HTTP y garantía de entrega del catálogo de Roboteka. ¿No hay el escenario que necesitas? Describe la tarea, hacemos el robot gratis.