Un webhook en Bitrix24 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.ru/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.

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.