Saltar a contenido

Webhooks

Los Webhooks permiten que el Orquestador de BotCity envíe eventos operativos en tiempo real a cualquier endpoint HTTP que configures, ya sea Slack, Microsoft Teams, Datadog, Power BI, Google Chat o cualquier otra herramienta. De esta forma, recibes las notificaciones en el momento en que ocurren, sin necesidad de consultar periódicamente la API del Orquestador ni mantener una automatización auxiliar solo para eso.

¿Quién tiene acceso?

Los Webhooks están disponibles solo en planes de pago. Solo los usuarios con el rol de Administrador pueden crear, editar, eliminar, activar o desactivar webhooks.

Captura de pantalla del Orquestador de BotCity, que muestra la página de Webhooks del Integration Hub. La página muestra el botón New Webhook en la esquina superior derecha, un campo de búsqueda y la sección Your Webhooks con dos tarjetas: "errors-events", activa, con 6 eventos en total (Task, Runner, Alert, Datapool), y "follow-up-events", activa, con 5 eventos en total (Task, Runner, Alert, Datapool).

Crear un webhook

  1. Accede a Integration Hub > Webhooks en el menú lateral.
  2. Haz clic en Novo Webhook +.
  3. Indica:
    • Nombre: un nombre descriptivo para identificar el webhook.
    • URL del endpoint: la URL HTTP que recibirá los eventos.
    • Selecciona los eventos: al menos uno de los eventos admitidos, de cualquier categoría.
  4. Haz clic en Guardar en la esquina superior derecha.

  5. La plataforma genera una clave de firma HMAC y muestra un botón para copiarla.

    Guarda la clave

    La clave de firma solo se muestra en texto claro en ese momento. Cópiala y guárdala en un lugar seguro, no se mostrará de nuevo.

  6. Se creará una tarjeta en la página de webhooks, que puedes activar y desactivar cuando lo necesites.

  7. Mientras esté activo, cada vez que ocurra uno de los eventos seleccionados, la plataforma envía un POST a la URL indicada.

Organización de notificaciones

Puedes combinar eventos de distintas categorías en un único webhook o crear webhooks separados por categoría, o por destino.

Por ejemplo:

  • Fallas: Tarea con falla, Runner sin conexión e Item con error de negocio
  • Seguimiento: Tarea inició ejecución, Runner en línea e Item finalizado con éxito

Eventos admitidos

Cada webhook escucha los eventos que selecciones entre las cuatro categorías siguientes.

Tarea

Evento Cuándo se dispara
Tarea inició ejecución Cuando el Runner comienza a ejecutar una tarea.
Tarea finalizada con éxito Cuando una tarea se completa con éxito.
Tarea con falla Cuando una tarea falla durante la ejecución.
Tarea parcialmente finalizada Cuando una tarea finaliza con parte de los items procesados y parte sin procesar.
Tarea en timeout Cuando una tarea supera el tiempo de ejecución configurado.
Tarea cancelada Cuando una tarea se cancela antes de iniciar la ejecución.

Runner

Evento Cuándo se dispara
Runner quedó sin conexión Cuando un Runner pierde la conexión con el Orquestador.
Runner volvió a conectarse Cuando un Runner establece la conexión con el Orquestador.

Alerta

Evento Cuándo se dispara
Alerta de error emitida Cuando se emite una alerta de tipo error durante la ejecución de una automatización.
Alerta de aviso emitida Cuando se emite una alerta de tipo aviso durante la ejecución de una automatización.

Datapool

Evento Cuándo se dispara
Item finalizado con error tipo SISTEMA Cuando un item del Datapool finaliza con un error de sistema.
Item finalizado con error tipo NEGOCIO Cuando un item del Datapool finaliza con un error de regla de negocio.
Item en timeout Cuando un item del Datapool supera el tiempo de procesamiento configurado.
Item finalizado con éxito Cuando un item del Datapool finaliza con éxito.
Datapool con volumen alto de errores Cuando el 50% del total de items procesados resulta en error de Datapool.

Configurar el destino de los eventos

Todo webhook envía el payload del evento del Orquestador de BotCity a la URL HTTP que configures.

Herramientas específicas

En esta versión no existe una integración nativa que traduzca ese payload al formato de mensaje de una herramienta específica como Slack, Microsoft Teams o Google Chat.

Para recibir los eventos, debes mantener un endpoint HTTP propio, responsable de procesar el payload del Orquestador de BotCity y, si corresponde, reenviar la información a la herramienta de destino (Slack, Microsoft Teams, Datadog, Power BI, Google Chat, entre otras) en el formato que ella espera.

Tu endpoint necesita:

  • Estar accesible públicamente vía HTTPS, en la URL indicada al crear el webhook.
  • Aceptar solicitudes POST con cuerpo en JSON.
  • Validar la firma HMAC enviada en cada solicitud, según se describe en Autenticación.
  • Responder dentro del límite de 1 segundo, conforme a la política de reintentos y timeout.

Las siguientes secciones detallan el contrato entre el Orquestador y tu endpoint: cómo validar la autenticidad de las solicitudes, cuál es la estructura del payload enviado para cada tipo de evento y cómo el Orquestador maneja las fallas y los reenvíos.

Autenticación

Todo envío está firmado con HMAC-SHA256 y se envía en el header X-BotCity-Signature-256. Usa la clave de firma generada al crear el webhook para validar esa firma en tu endpoint antes de procesar el payload.

Valida siempre la firma

Si tu endpoint no valida la firma, cualquier persona que descubra la URL podrá enviarle solicitudes forjadas. La validación es responsabilidad de la aplicación que recibe el webhook.

Ejemplo de validación

import hashlib
import hmac

def validar_firma(payload: bytes, firma_recibida: str, clave_secreta: str) -> bool:
    firma_calculada = hmac.new(
        key=clave_secreta.encode("utf-8"),
        msg=payload,
        digestmod=hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(firma_calculada, firma_recibida)

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;

public boolean validarFirma(byte[] payload, String firmaRecibida, String claveSecreta) throws Exception {
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(claveSecreta.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));

    StringBuilder hex = new StringBuilder();
    for (byte b : mac.doFinal(payload)) {
        hex.append(String.format("%02x", b));
    }

    return MessageDigest.isEqual(
        hex.toString().getBytes(StandardCharsets.UTF_8),
        firmaRecibida.getBytes(StandardCharsets.UTF_8)
    );
}

Valida siempre sobre el cuerpo bruto

Calcula la firma sobre el cuerpo de la solicitud bruto (antes de cualquier parseo de JSON). Parsear primero y volver a serializar puede generar una cadena distinta de la que firmó la BotPlataforma.

Estructura del payload

Todo evento llega con la misma estructura: id, type, date y body. El contenido de body cambia según el tipo de evento.

Ejemplo de payload

{
  "id": "uuid-del-evento",
  "type": "TASK_FINISHED",
  "date": "2026-05-11T11:00:00",
  "body": {
    "taskId": 123,
    "automationName": "...",
    "workspace": "...",
    "runner": "...",
    "durationMs": 67890,
    "itemsSuccess": 100,
    "itemsError": 2,
    "finishMessage": "..."
  }
}

{
  "id": "uuid-del-evento",
  "type": "RUNNER_OFFLINE",
  "date": "2026-05-11T11:00:00",
  "body": {
    "runnerId": "...",
    "runnerName": "...",
    "workspace": "...",
    "lastHeartbeat": "2026-05-11T10:58:30"
  }
}

{
  "id": "uuid-del-evento",
  "type": "ALERT_ERROR",
  "date": "2026-05-11T11:00:00",
  "body": {
    "taskId": 123,
    "automationName": "...",
    "workspace": "...",
    "runner": "...",
    "severity": "ERROR",
    "message": "..."
  }
}

{
  "id": "uuid-del-evento",
  "type": "DATAPOOL_ITEM_ERROR",
  "date": "2026-05-11T11:00:00",
  "body": {
    "datapoolId": "...",
    "datapoolLabel": "...",
    "itemId": "...",
    "workspace": "...",
    "errorType": "SYSTEM",
    "errorMessage": "..."
  }
}

Evita procesar eventos duplicados

Cada evento tiene un id único. Úsalo para verificar duplicados de tu lado, el modelo de entrega es at-least-once, es decir, el mismo evento puede, en casos raros, llegar más de una vez.

Política de reintentos y timeout

El envío es asíncrono: una falla en tu endpoint nunca afecta la ejecución de la automatización.

  • Timeout: tu endpoint tiene 1 segundo para responder.
  • Reintentos: hasta 3 intentos, con backoff exponencial entre ellos.
  • Error 4xx: este tipo de error se trata como una falla definitiva, sin intentar reenviar.
    • Ejemplo: falla de autenticación o payload inválido de tu lado.
  • Status Code: el Orquestador valida únicamente el status code de la respuesta, el cuerpo de la respuesta no se lee.
    • Éxito = 2xx

Responde rápido, procesa después

Tu endpoint debe limitarse a recibir y encolar el evento. Cualquier procesamiento más pesado debe ocurrir fuera del camino síncrono del webhook, para no superar el timeout de 1 segundo.

Detalles del webhook

Después de crear tus Webhooks, tienes la opción de:

  • Activar / desactivar: alterna el estado del webhook directamente desde la tarjeta, sin necesidad de eliminarlo y volver a crearlo.
  • Visualizar: haz clic en el nombre del Webhook para abrir la página de detalles.
  • Menú de opciones:
    • Edit: cambia el nombre, la URL del endpoint o los eventos seleccionados.
    • Delete: elimina el webhook de forma definitiva. Esta acción no se puede deshacer.

Visualizar

Al acceder a la página de tu Webhook, encontrarás la información organizada en bloques.

Información general

  • Nombre: el nombre definido para el webhook.
  • URL: el endpoint que recibe los eventos.
  • Clave secreta: permite generar una nueva clave de firma HMAC, invalidando la anterior.
  • Eventos: los eventos seleccionados para ese webhook, agrupados por categoría.

Captura de pantalla del Orquestador de BotCity, que muestra la página de detalles de un webhook. La página muestra los botones Delete y Edit en la esquina superior derecha, los campos Name y URL, la sección Secret Key con el botón Generate new key, la sección Events con la categoría Task expandida mostrando el evento Task started execution, y la sección Deliveries overview con el campo Filter by, los filtros Start Date y End Date y una tabla con las columnas Status, Event, Timestamp, Duration y HTTP.

Resumen de entregas

En este bloque encontrarás una tabla con todos los intentos de envío:

  • Status: si la entrega se completó con éxito o falló.
  • Evento: el evento que disparó el envío.
  • Fecha y hora: cuándo ocurrió el intento de envío.
  • Duración: cuánto tiempo tardó tu endpoint en responder.
  • HTTP: el status code HTTP devuelto por tu endpoint.
  • Payload: cada fila se puede expandir para mostrar el payload enviado en ese intento, con un botón para copiarlo.

También puedes filtrar las entregas por status o evento, y por período usando Data de inicio y Data de fin.

La respuesta de tu endpoint no se muestra

La tabla muestra el payload enviado por el Orquestador, pero no el cuerpo de la respuesta de tu endpoint, ya que la plataforma valida únicamente el status code.

Captura de pantalla del Orquestador de BotCity, que muestra la pantalla Deliveries overview de un webhook. La pantalla muestra el campo Filter by y los filtros Start Date y End Date, además de una tabla con las columnas Status, Event, Timestamp, Duration y HTTP. La primera fila, con estado Failed, está expandida mostrando el payload enviado en formato JSON y un botón para copiarlo.

Desactivación automática

Si un webhook acumula 10 entregas consecutivas con falla, se desactiva automáticamente. Un banner en la pantalla del webhook explica el motivo, con un enlace al historial de entregas.

La reactivación siempre es manual, realizada por un Administrador.

Límites y permisos

  • Disponible solo en planes de pago.
  • Solo el rol Administrador puede crear, editar, eliminar, activar o desactivar webhooks.
  • Límite de 10 webhooks por workspace. Al alcanzar el límite, el botón de creación se deshabilita.