API Documentation

The Webhook API lets you sync structured data (JSON or XML) with a Bravos AI bot. You can perform an initial load from a URL and keep the data updated through HTTP webhooks signed with HMAC-SHA256.

Before sending webhooks, you need to configure the connection from Integrations > Custom Webhook in the admin panel.

1. 1

   Create the connection

   Give it a descriptive name (e.g. "Clinics", "Inventory") and provide the URL where your data lives in JSON or XML format (max 50 MB). The system will download the data and detect fields automatically.

2. 2

   Choose the identifier field

   Once the connection is created, the system detects fields from your data. Select which one is the unique identifier for each record (like a primary key). For example: id, ref, sku. This field is required in every item you send via webhook.

3. 3

   Activate and collect your credentials

   When you activate, the system processes the initial load from your URL. From that point you have:

   • Endpoint — the URL to send webhooks to
   • Secret — the key to sign each request with HMAC-SHA256
   • Dataset slug and Bot ID — already included in the endpoint

Once activated, you can exclude fields from the admin panel so the chatbot doesn't use them in responses.

Every request must include an HMAC-SHA256 signature in the X-Bravos-Signature header. It's computed over the entire body using your secret. The format is hex lowercase.

import hmac, hashlib

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

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

If the signature doesn't match, the server responds with 401. After 10 failed attempts within a minute, the endpoint is temporarily blocked.

Send "action": "upsert" with an array of items. If an item with the same identifier already exists, it gets updated. Otherwise, it gets created.

{
  "action": "upsert",
  "items": [
    {
      "ref": "MAD-01",
      "name": "Madrid Central Clinic",
      "address": "Calle Gran Via 30",
      "phone": "+34 910 000 000",
      "specialties": ["Dentistry", "Orthopedics", "Dermatology"],
      "schedule": {
        "weekdays": "09:00 - 20:00",
        "saturdays": "10:00 - 14:00"
      },
      "services": [
        {"name": "Dental cleaning", "price": 60, "duration_min": 45},
        {"name": "Panoramic X-ray", "price": 35, "duration_min": 15},
        {"name": "Dermatology consultation", "price": 80, "duration_min": 30}
      ]
    }
  ]
}

Each item must include the field you chose as identifier when activating the connection (in this example, ref). All other fields are flexible and are detected automatically.

Send "action": "delete" with the identifiers of the records to remove. Deletion includes associated sub-records.

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

Deleting a nonexistent record won't produce an error. The operation is idempotent.