Documentación API

La Webhook API te permite sincronizar datos estructurados (JSON o XML) con un bot de Bravos AI. Puedes realizar una carga inicial desde una URL y mantener los datos actualizados mediante webhooks HTTP firmados con HMAC-SHA256.

Antes de enviar webhooks, necesitas configurar la conexión desde Integraciones > Webhook personalizado en el panel de administración.

1. 1

   Crea la conexión

   Dale un nombre descriptivo (ej: "Clínicas", "Inventario") y proporciona la URL donde están tus datos en formato JSON o XML (máximo 50 MB). El sistema descargará los datos y detectará los campos automáticamente.

2. 2

   Elige el campo identificador

   Una vez creada la conexión, el sistema detecta los campos de tus datos. Selecciona cuál es el identificador único de cada registro (equivalente a una clave primaria). Por ejemplo: id, ref, sku. Este campo es obligatorio en cada item que envíes por webhook.

3. 3

   Activa y recoge tus credenciales

   Al activar, el sistema procesa la carga inicial desde tu URL. A partir de ese momento tienes disponible:

   • Endpoint — la URL a la que enviar webhooks
   • Secret — la clave para firmar cada request con HMAC-SHA256
   • Dataset slug y Bot ID — ya incluidos en el endpoint

Una vez activada, puedes excluir campos desde el panel para que el chatbot no los use en sus respuestas.

Cada request debe incluir una firma HMAC-SHA256 en el header X-Bravos-Signature. Se calcula sobre el body completo usando tu secret. El formato es hex en minúsculas.

import hmac, hashlib

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

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

Si la firma no coincide, el servidor responde 401. Tras 10 intentos fallidos en un minuto, el endpoint se bloquea temporalmente.

Envía "action": "upsert" con un array de items. Si un item con el mismo identificador ya existe, se actualiza. Si no existe, se crea.

{
  "action": "upsert",
  "items": [
    {
      "ref": "MAD-01",
      "nombre": "Clínica Madrid Centro",
      "dirección": "Calle Gran Vía 30",
      "teléfono": "+34 910 000 000",
      "especialidades": ["Odontología", "Traumatología", "Dermatología"],
      "horario": {
        "lunes_viernes": "09:00 - 20:00",
        "sábados": "10:00 - 14:00"
      },
      "servicios": [
        {"nombre": "Limpieza dental", "precio": 60, "duración_min": 45},
        {"nombre": "Radiografía panorámica", "precio": 35, "duración_min": 15},
        {"nombre": "Consulta dermatológica", "precio": 80, "duración_min": 30}
      ]
    }
  ]
}

Cada item debe incluir el campo que elegiste como identificador al activar la conexión (en este ejemplo, ref). El resto de campos son libres y se detectan automáticamente.

Envía "action": "delete" con los identificadores de los registros a eliminar. La eliminación incluye los sub-registros asociados.

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

Eliminar un registro inexistente no produce error. La operación es idempotente.