Documentação da API

A Webhook API permite sincronizar dados estruturados (JSON ou XML) com um bot da Bravos AI. Você pode fazer uma carga inicial a partir de uma URL e manter os dados atualizados por meio de webhooks HTTP assinados com HMAC-SHA256.

Antes de enviar webhooks, você precisa configurar a conexão em Integrações > Webhook personalizado no painel de administração.

1. 1

   Crie a conexão

   Dê a ela um nome descritivo (ex.: "Clínicas", "Inventário") e informe a URL onde estão os seus dados em formato JSON ou XML (máximo de 50 MB). O sistema baixará os dados e detectará os campos automaticamente.

2. 2

   Escolha o campo identificador

   Depois de criar a conexão, o sistema detecta os campos dos seus dados. Selecione qual é o identificador único de cada registro (equivalente a uma chave primária). Por exemplo: id, ref, sku. Este campo é obrigatório em cada item que você enviar por webhook.

3. 3

   Ative e recolha suas credenciais

   Ao ativar, o sistema processa a carga inicial a partir da sua URL. A partir desse momento você tem disponível:

   • Endpoint — a URL para a qual enviar os webhooks
   • Secret — a chave para assinar cada request com HMAC-SHA256
   • Dataset slug e Bot ID — já incluídos no endpoint

Depois de ativada, você pode excluir campos pelo painel para que o chatbot não os use nas respostas.

Cada request deve incluir uma assinatura HMAC-SHA256 no header X-Bravos-Signature. Ela é calculada sobre o body completo usando o seu secret. O formato é hex em minúsculas.

import hmac, hashlib

secret = "SEU_SECRET_AQUI"
body = b'{"action":"upsert","items":[...]}'

signature = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
# Resultado: "a1b2c3d4..." (hex lowercase)

Se a assinatura não coincidir, o servidor responde 401. Depois de 10 tentativas com falha em um minuto, o endpoint é bloqueado temporariamente.

Envie "action": "upsert" com um array de itens. Se um item com o mesmo identificador já existe, ele é atualizado. Se não existe, é criado.

{
  "action": "upsert",
  "items": [
    {
      "ref": "SP-01",
      "nome": "Clínica São Paulo Centro",
      "endereco": "Av. Paulista, 1000",
      "telefone": "+55 11 3000-0000",
      "especialidades": ["Odontologia", "Ortopedia", "Dermatologia"],
      "horario": {
        "segunda_sexta": "09:00 - 20:00",
        "sabados": "10:00 - 14:00"
      },
      "servicos": [
        {"nome": "Limpeza dental", "preco": 250, "duracao_min": 45},
        {"nome": "Radiografia panorâmica", "preco": 150, "duracao_min": 15},
        {"nome": "Consulta dermatológica", "preco": 350, "duracao_min": 30}
      ]
    }
  ]
}

Cada item deve incluir o campo que você escolheu como identificador ao ativar a conexão (neste exemplo, ref). Os demais campos são livres e são detectados automaticamente.

Envie "action": "delete" com os identificadores dos registros a excluir. A exclusão inclui os sub-registros associados.

{
  "action": "delete",
  "items": [
    { "ref": "SP-01" }
  ]
}

Excluir um registro inexistente não produz erro. A operação é idempotente.