Ir para o conteúdo

Webhooks

Os Webhooks permitem que o Orquestrador BotCity envie eventos operacionais em tempo real para qualquer endpoint HTTP que você configurar, seja Slack, Microsoft Teams, Datadog, Power BI, Google Chat ou qualquer outra ferramenta. Desta forma, você recebe as notificações assim que elas acontecem, sem precisar consultar a API do Orquestrador periodicamente ou manter uma automação auxiliar só para isso.

Quem tem acesso?

Webhooks estão disponíveis apenas em planos pagos. Somente usuários com papel de Administrador podem criar, editar, excluir, ativar ou desativar webhooks.

Captura de tela do Orquestrador da BotCity, apresentando a página Webhooks do Integration Hub. A página exibe o botão New Webhook no canto superior direito, um campo de busca e a seção Your Webhooks com dois cards: "errors-events", ativo, com 6 eventos no total (Task, Runner, Alert, Datapool), e "follow-up-events", ativo, com 5 eventos no total (Task, Runner, Alert, Datapool).

Criar um webhook

  1. Acesse Integration Hub > Webhooks no menu lateral.
  2. Clique em Novo Webhook +.
  3. Informe:
    • Nome: um nome descritivo para identificar o webhook.
    • URL do endpoint: a URL HTTP que vai receber os eventos.
    • Selecione os eventos: pelo menos um dos eventos suportados, de qualquer categoria.
  4. Clique em Salvar no canto superior direito.

  5. A plataforma gera uma chave de assinatura HMAC e exibe um botão de cópia.

    Guarde a chave

    A chave de assinatura só é exibida em texto claro nesse momento. Copie e guarde em local seguro, ela não será mostrada novamente.

  6. Um card será criado na página de webhooks, você pode ativar e desativar sempre que necessário.

  7. Quando ativo, sempre que um dos eventos selecionados ocorrer, a plataforma envia um POST para a URL informada.

Organização de notificações

Você pode combinar eventos de categorias diferentes em um único webhook ou criar webhooks separados por categoria, ou destino.

Por exemplo:

  • Falhas: Tarefa com falha, Runner offline e Item com erro de negócio
  • Acompanhamento: Tarefa iniciou execução, Runner ficou online e Item finalizado com sucesso

Eventos suportados

Cada webhook escuta os eventos que você selecionar entre as quatro categorias abaixo.

Tarefa

Evento Quando é disparado
Tarefa iniciou execução Quando o Runner inicia a execução de uma tarefa.
Tarefa finalizada com sucesso Quando uma tarefa é concluída com sucesso.
Tarefa com falha Quando uma tarefa falha durante a execução.
Tarefa parcialmente finalizada Quando uma tarefa finaliza com parte dos itens processados e parte não processados.
Tarefa em timeout Quando uma tarefa excede o tempo configurado de execução.
Tarefa cancelada Quando uma tarefa é cancelada antes de iniciar a execução.

Runner

Evento Quando é disparado
Runner ficou offline Quando um Runner perde a conexão com o Orquestrador.
Runner voltou online Quando um Runner estabelece a conexão com o Orquestrador.

Alerta

Evento Quando é disparado
Alerta de erro emitido Quando um alerta do tipo erro é emitido durante a execução de uma automação.
Alerta de aviso emitido Quando um alerta do tipo aviso é emitido durante a execução de uma automação.

Datapool

Evento Quando é disparado
Item finalizado com erro tipo SISTEMA Quando um item do Datapool finaliza com erro de sistema.
Item finalizado com erro tipo NEGÓCIO Quando um item do Datapool finaliza com erro de regra de negócio.
Item em timeout Quando um item do Datapool excede o tempo configurado de processamento.
Item finalizado com sucesso Quando um item do Datapool finaliza com sucesso.
Datapool com volume alto de erros Quando 50% do total dos itens processar com erro Datapool.

Configurando o destino dos eventos

Todo webhook envia o payload de evento do Orquestrador BotCity para a URL HTTP que você configurar.

Ferramentas específicas

Não existe, nesta versão, uma integração nativa que traduza esse payload para o formato de mensagem de uma ferramenta específica como Slack, Microsoft Teams ou Google Chat.

Para receber os eventos, você mantém um endpoint HTTP próprio, responsável por processar o payload do Orquestrador BotCity e, se for o caso, repassar a informação para a ferramenta de destino (Slack, Microsoft Teams, Datadog, Power BI, Google Chat, entre outras) no formato que ela espera.

Seu endpoint precisa:

  • Estar acessível publicamente via HTTPS, na URL informada ao criar o webhook.
  • Aceitar requisições POST com corpo em JSON.
  • Validar a assinatura HMAC enviada em cada requisição, conforme descrito em Autenticação.
  • Responder dentro do tempo limite de 1 segundo, conforme a política de reenvio e timeout.

As seções a seguir detalham o contrato entre o Orquestrador e o seu endpoint: como validar a autenticidade das requisições, qual é a estrutura do payload enviado para cada tipo de evento e como o Orquestrador lida com falhas e reentregas.

Autenticação

Todo disparo é assinado com HMAC-SHA256 e enviado no header X-BotCity-Signature-256. Use a chave de assinatura gerada na criação do webhook para validar essa assinatura no seu endpoint antes de processar o payload.

Valide sempre a assinatura

Se o seu endpoint não validar a assinatura, qualquer pessoa que descubra a URL poderá enviar requisições forjadas para ele. A validação é responsabilidade da aplicação que recebe o webhook.

Exemplo de validação

import hashlib
import hmac

def valida_assinatura(payload: bytes, assinatura_recebida: str, chave_secreta: str) -> bool:
    assinatura_calculada = hmac.new(
        key=chave_secreta.encode("utf-8"),
        msg=payload,
        digestmod=hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(assinatura_calculada, assinatura_recebida)

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

public boolean validaAssinatura(byte[] payload, String assinaturaRecebida, String chaveSecreta) throws Exception {
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(chaveSecreta.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),
        assinaturaRecebida.getBytes(StandardCharsets.UTF_8)
    );
}

Sempre valide sobre o corpo bruto

Calcule a assinatura sobre o corpo da requisição bruto (antes de qualquer parse de JSON). Fazer o parse primeiro e serializar de volta pode gerar uma string diferente da que a BotPlataforma assinou.

Estrutura do payload

Todo evento chega com a mesma estrutura: id, type, date e body. O conteúdo de body muda conforme o tipo de evento.

Exemplo de payload

{
  "id": "uuid-do-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-do-evento",
  "type": "RUNNER_OFFLINE",
  "date": "2026-05-11T11:00:00",
  "body": {
    "runnerId": "...",
    "runnerName": "...",
    "workspace": "...",
    "lastHeartbeat": "2026-05-11T10:58:30"
  }
}

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

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

Evite processar eventos duplicados

Cada evento tem um id único. Use-o para verificar duplicidade do seu lado, o modelo de entrega é at-least-once, ou seja, o mesmo evento pode, em casos raros, chegar mais de uma vez.

Política de reenvio e timeout

O disparo é assíncrono: uma falha no seu endpoint nunca afeta a execução da automação.

  • Timeout: seu endpoint tem 1 segundo para responder.
  • Reenviar: até 3 tentativas, com backoff exponencial entre elas.
  • Erro 4xx: esse tipo de erro é tratado como falha definitiva, sem tentar reenviar.
    • Exemplo: falha de autenticação ou payload inválido do seu lado.
  • Status Code: O Orquestrador valida apenas o status code da resposta, o corpo da resposta não é lido.
    • Sucesso = 2xx

Responda rápido, processe depois

Seu endpoint deve apenas receber e enfileirar o evento. Qualquer processamento mais pesado deve acontecer fora do caminho síncrono do webhook, para não estourar o timeout de 1 segundo.

Detalhes do webhook

Após a criação dos seus Webhooks, você tem a opção de:

  • Ativar / desativar: alterna o status do webhook direto pelo card, sem precisar excluir e recriar.
  • Visualizar: clique no nome do Webhook para abrir a página de detalhes.
  • Menu de opções:
    • Editar: altera o nome, a URL do endpoint ou os eventos selecionados.
    • Excluir: remove o webhook definitivamente. Essa ação não pode ser desfeita.

Visualizar

Ao acessar a página do seu Webhook, você encontra as informações em blocos.

Informações gerais

  • Nome: o nome definido para o webhook.
  • URL: o endpoint que recebe os eventos.
  • Chave secreta: permite gerar uma nova chave de assinatura HMAC, invalidando a anterior.
  • Eventos: os eventos selecionados para esse webhook, agrupados por categoria.

Captura de tela do Orquestrador da BotCity, apresentando a página de detalhes de um webhook. A página exibe os botões Delete e Edit no canto superior direito, os campos Name e URL, a seção Secret Key com o botão Generate new key, a seção Events com a categoria Task expandida mostrando o evento Task started execution, e a seção Deliveries overview com o campo Filter by, os filtros Start Date e End Date e uma tabela com as colunas Status, Event, Timestamp, Duration e HTTP.

Visão geral das entregas

Nesse bloco você encontra uma tabela com todas as tentativas de envio:

  • Status: se a entrega foi concluída com sucesso ou falhou.
  • Evento: o evento que disparou o envio.
  • Data e hora: quando a tentativa de envio ocorreu.
  • Duração: quanto tempo o seu endpoint levou para responder.
  • HTTP: o status code HTTP retornado pelo seu endpoint.
  • Payload: Cada linha pode ser expandida para mostrar o payload enviado naquela tentativa, com um botão para copiá-lo.

Você também pode filtrar as entregas por status ou evento, e por período usando Data inicial e Data final.

A resposta do seu endpoint não é exibida

A tabela mostra o payload enviado pelo Orquestrador, mas não o corpo da resposta do seu, endpoint pois a plataforma valida apenas o status code.

Captura de tela do Orquestrador da BotCity, apresentando a tela Deliveries overview de um webhook. A tela exibe o campo Filter by e os filtros Start Date e End Date, além de uma tabela com as colunas Status, Event, Timestamp, Duration e HTTP. A primeira linha, com status Failed, está expandida mostrando o payload enviado em formato JSON e um botão para copiá-lo.

Desativação automática

Se um webhook acumular 10 entregas consecutivas com falha, ele é desativado automaticamente. Um banner na tela do webhook explica o motivo, com link para o histórico de entregas.

A reativação é sempre manual, feita por um Administrador.

Limites e permissões

  • Disponível apenas em planos pagos.
  • Apenas o papel Administrador pode criar, editar, excluir, ativar ou desativar webhooks.
  • Limite de 10 webhooks por workspace. Ao atingir o limite, o botão de criação é desabilitado.