Aller au contenu
Menu

Rechercher sur le site

Tape pour chercher dans les guides, le blog, l'API et le produit.

↑ ↓ pour naviguer · Entrée pour ouvrir · Échap pour fermer

Référence de l'API

API

Webhooks

Prévenez votre système, instantanément et de façon signée, quand quelque chose se passe dans votre agent

Voir en Markdown

Un webhook est une URL de votre système à laquelle TBit envoie un POST signé chaque fois que quelque chose se passe dans votre agent : un rendez-vous est planifié, replanifié ou annulé, une commande est payée ou l'IA transmet une conversation à l'équipe. Ainsi votre agenda, votre ERP ou votre CRM sont informés sans avoir à demander.

Les webhooks se créent ici avec l'API, dans l'application (Plugins › Développement › Webhooks) ou depuis le MCP avec manage_webhooks. Les trois portes utilisent les mêmes noms : url, events, description et status. Jusqu'à 10 par agent.

MéthodeRouteDescription
GET/v1/webhooksListe les webhooks, chacun avec ses 5 dernières livraisons
POST/v1/webhooksCrée un webhook ; renvoie le secret une seule fois
GET/v1/webhooks/{id}Un webhook avec ses dernières livraisons (?limit= jusqu'à 100)
PATCH/v1/webhooks/{id}Modifie url, events, description ou status
DELETE/v1/webhooks/{id}Supprime le webhook
POST/v1/webhooks/{id}/testEnvoie immédiatement un événement webhook.test signé et renvoie ce que votre système a répondu

Créer un webhook

Champs : url (https et publique : les IP privées, localhost et adresses internes ne sont pas acceptés), events (au moins un de la table des événements) et description (facultatif, jusqu'à 200 caractères). La réponse contient secret : conservez-le, c'est la seule fois qu'il apparaît et c'est avec lui que vous vérifiez chaque livraison.

POST/v1/webhooks
curl -X POST "https://rest-api.tbit.app/v1/webhooks" \
  -H "X-API-Key: $TBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tu-sistema.com/webhooks/tbit",
    "events": [
      "appointment.created",
      "appointment.cancelled"
    ],
    "description": "Agenda del consultorio"
  }'
const response = await fetch('https://rest-api.tbit.app/v1/webhooks', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.TBIT_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://tu-sistema.com/webhooks/tbit',
    events: [
      'appointment.created',
      'appointment.cancelled',
    ],
    description: 'Agenda del consultorio',
  }),
});
const data = await response.json();
import axios from 'axios';

const { data } = await axios.post(
  'https://rest-api.tbit.app/v1/webhooks',
  {
    url: 'https://tu-sistema.com/webhooks/tbit',
    events: [
      'appointment.created',
      'appointment.cancelled',
    ],
    description: 'Agenda del consultorio',
  },
  {
    headers: {
      'X-API-Key': process.env.TBIT_API_KEY,
    },
  },
);
import os
import requests

response = requests.post(
    'https://rest-api.tbit.app/v1/webhooks',
    headers={'X-API-Key': os.environ['TBIT_API_KEY']},
    json={
        'url': 'https://tu-sistema.com/webhooks/tbit',
        'events': [
            'appointment.created',
            'appointment.cancelled',
        ],
        'description': 'Agenda del consultorio',
    },
)
data = response.json()
<?php
$ch = curl_init('https://rest-api.tbit.app/v1/webhooks');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('TBIT_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'url' => 'https://tu-sistema.com/webhooks/tbit',
        'events' => [
            'appointment.created',
            'appointment.cancelled',
        ],
        'description' => 'Agenda del consultorio',
    ]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
Réponse
{
  "data": {
    "webhook": {
      "webhook_id": "6b1d2e3f4a5b6c7d8e9f0a2d",
      "url": "https://tu-sistema.com/webhooks/tbit",
      "events": [
        "appointment.created",
        "appointment.cancelled"
      ],
      "description": "Agenda del consultorio",
      "status": "active",
      "disabled_reason": null,
      "failure_streak": 0,
      "last_delivery_at": null,
      "created_at": "2026-11-19T15:00:00.000Z"
    },
    "secret": "whsec_9c1f…(64 caracteres hex)"
  }
}

Chaque webhook contient recent_deliveries : l'événement, le statut (delivered, pending ou failed), les tentatives, le code HTTP que votre système a renvoyé et le temps que cela a pris. Les livraisons sont conservées 30 jours.

GET/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d
curl "https://rest-api.tbit.app/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d?limit=20" \
  -H "X-API-Key: $TBIT_API_KEY"
const response = await fetch('https://rest-api.tbit.app/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d?limit=20', {
  headers: {
    'X-API-Key': process.env.TBIT_API_KEY,
  },
});
const data = await response.json();
import axios from 'axios';

const { data } = await axios.get(
  'https://rest-api.tbit.app/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d?limit=20',
  {
    headers: {
      'X-API-Key': process.env.TBIT_API_KEY,
    },
  },
);
import os
import requests

response = requests.get(
    'https://rest-api.tbit.app/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d?limit=20',
    headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()
<?php
$ch = curl_init('https://rest-api.tbit.app/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d?limit=20');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('TBIT_API_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
Réponse
{
  "data": {
    "webhook": {
      "webhook_id": "6b1d2e3f4a5b6c7d8e9f0a2d",
      "url": "https://tu-sistema.com/webhooks/tbit",
      "events": [
        "appointment.created"
      ],
      "status": "active",
      "failure_streak": 0,
      "recent_deliveries": [
        {
          "delivery_id": "6b1d2e3f4a5b6c7d8e9f0a3e",
          "event_id": "evt_3f1c9a7e2b6d4c58a0e1f2b3c4d5e6f7",
          "type": "appointment.created",
          "status": "delivered",
          "attempts": 1,
          "http_status": 200,
          "duration_ms": 184,
          "error": null,
          "created_at": "2026-11-19T15:02:11.000Z",
          "delivered_at": "2026-11-19T15:02:31.000Z",
          "next_attempt_at": null
        }
      ]
    }
  }
}

N'envoyez que ce qui change. "status": "disabled" désactive le webhook sans le supprimer ; "status": "active" le réactive et remet à zéro le compteur d'échecs (ainsi on réactive un webhook que TBit a désactivé).

PATCH/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d
curl -X PATCH "https://rest-api.tbit.app/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d" \
  -H "X-API-Key: $TBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      "appointment.created",
      "order.paid"
    ],
    "status": "active"
  }'
const response = await fetch('https://rest-api.tbit.app/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.TBIT_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    events: [
      'appointment.created',
      'order.paid',
    ],
    status: 'active',
  }),
});
const data = await response.json();
import axios from 'axios';

const { data } = await axios.patch(
  'https://rest-api.tbit.app/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d',
  {
    events: [
      'appointment.created',
      'order.paid',
    ],
    status: 'active',
  },
  {
    headers: {
      'X-API-Key': process.env.TBIT_API_KEY,
    },
  },
);
import os
import requests

response = requests.patch(
    'https://rest-api.tbit.app/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d',
    headers={'X-API-Key': os.environ['TBIT_API_KEY']},
    json={
        'events': [
            'appointment.created',
            'order.paid',
        ],
        'status': 'active',
    },
)
data = response.json()
<?php
$ch = curl_init('https://rest-api.tbit.app/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('TBIT_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'events' => [
            'appointment.created',
            'order.paid',
        ],
        'status' => 'active',
    ]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
DELETE/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d
curl -X DELETE "https://rest-api.tbit.app/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d" \
  -H "X-API-Key: $TBIT_API_KEY"
const response = await fetch('https://rest-api.tbit.app/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.TBIT_API_KEY,
  },
});
const data = await response.json();
import axios from 'axios';

const { data } = await axios.delete(
  'https://rest-api.tbit.app/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d',
  {
    headers: {
      'X-API-Key': process.env.TBIT_API_KEY,
    },
  },
);
import os
import requests

response = requests.delete(
    'https://rest-api.tbit.app/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d',
    headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()
<?php
$ch = curl_init('https://rest-api.tbit.app/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('TBIT_API_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

Envoyer un test

Envoie immédiatement un événement webhook.test signé avec le secret du webhook, même s'il est désactivé et même s'il n'est abonné à rien, et vous indique ce que votre système a répondu. Cela ne compte pas comme un échec pour la désactivation automatique. Limite : 20 par minute.

POST/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d/test
curl -X POST "https://rest-api.tbit.app/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d/test" \
  -H "X-API-Key: $TBIT_API_KEY"
const response = await fetch('https://rest-api.tbit.app/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d/test', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.TBIT_API_KEY,
  },
});
const data = await response.json();
import axios from 'axios';

const { data } = await axios.post(
  'https://rest-api.tbit.app/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d/test',
  {},
  {
    headers: {
      'X-API-Key': process.env.TBIT_API_KEY,
    },
  },
);
import os
import requests

response = requests.post(
    'https://rest-api.tbit.app/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d/test',
    headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()
<?php
$ch = curl_init('https://rest-api.tbit.app/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d/test');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('TBIT_API_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
Réponse
{
  "data": {
    "webhook_id": "6b1d2e3f4a5b6c7d8e9f0a2d",
    "delivery_id": "6b1d2e3f4a5b6c7d8e9f0a4f",
    "event_id": "evt_0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d",
    "ok": true,
    "http_status": 200,
    "duration_ms": 212,
    "error": null,
    "response": "ok",
    "receipt": "Tu sistema respondió 200 en 212 ms. La firma viaja en TBit-Signature."
  }
}
ÉvénementQuand il se produit
appointment.createdUn rendez-vous a été planifié (par l'IA, l'équipe dans l'app, le MCP ou l'API).
appointment.rescheduledUn rendez-vous a changé de date ou d'heure. Chaque changement est un événement.
appointment.cancelledUn rendez-vous a été annulé (y compris s'il est supprimé du Google Calendar connecté).
order.paidUne commande a été payée.
escalation.createdL'IA a transmis une conversation à l'équipe (escalade).
webhook.testUniquement avec « Envoyer un test ». Pas d'abonnement.

Les réservations de ressources que l'on loue (chambres, salles, véhicules) ne sortent pas encore comme appointment.*. L'événement de nouveau contact arrivera dans une prochaine version.

Toutes les livraisons ont la même forme : id (unique par événement : utilisez-le pour ne pas traiter deux fois), type, created_at (ISO 8601, UTC), agent_id et data, avec des champs plats. Les dates sont en UTC ; un champ sans valeur arrive en null.

appointment.rescheduled

Les mêmes champs, avec la nouvelle heure en start et end.

escalation.created

trigger indique qui l'a provoqué : cliente (l'a demandé), bot (l'IA l'a laissé entre les mains de l'équipe), energy_blocked (TBit n'a pas répondu par manque d'énergie) ou bot_guard (cela ressemblait à un système automatique).

json
{
  "id": "evt_3f1c9a7e2b6d4c58a0e1f2b3c4d5e6f7",
  "type": "appointment.created",
  "created_at": "2026-11-19T15:02:11.000Z",
  "agent_id": "66a54f2f2281f02197cb21bd",
  "data": {
    "appointment_id": "6b1d2e3f4a5b6c7d8e9f0a1b",
    "service_id": "6af9a1b2c3d4e5f6a7b8c9d0",
    "service_name": "Limpieza dental",
    "collaborator_id": "6af9a1b2c3d4e5f6a7b8c9d1",
    "collaborator_name": "Geral Díaz",
    "start": "2026-11-21T14:00:00.000Z",
    "end": "2026-11-21T14:45:00.000Z",
    "status": "CONFIRMED",
    "contact_id": "6ac9f1e6af6d42a269f21b15",
    "contact_name": "Ana Gómez",
    "phone": "+573001234567",
    "external_id": null,
    "order_id": "6b1d2e3f4a5b6c7d8e9f0a1c"
  }
}
json
{
  "id": "evt_8a2b0c4d6e8f0a1b2c3d4e5f6a7b8c9d",
  "type": "appointment.rescheduled",
  "created_at": "2026-11-19T15:02:11.000Z",
  "agent_id": "66a54f2f2281f02197cb21bd",
  "data": {
    "appointment_id": "6b1d2e3f4a5b6c7d8e9f0a1b",
    "service_id": "6af9a1b2c3d4e5f6a7b8c9d0",
    "service_name": "Limpieza dental",
    "collaborator_id": "6af9a1b2c3d4e5f6a7b8c9d1",
    "collaborator_name": "Geral Díaz",
    "start": "2026-11-22T16:00:00.000Z",
    "end": "2026-11-22T16:45:00.000Z",
    "status": "CONFIRMED",
    "contact_id": "6ac9f1e6af6d42a269f21b15",
    "contact_name": "Ana Gómez",
    "phone": "+573001234567",
    "external_id": null,
    "order_id": "6b1d2e3f4a5b6c7d8e9f0a1c"
  }
}
json
{
  "id": "evt_c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5",
  "type": "appointment.cancelled",
  "created_at": "2026-11-19T15:02:11.000Z",
  "agent_id": "66a54f2f2281f02197cb21bd",
  "data": {
    "appointment_id": "6b1d2e3f4a5b6c7d8e9f0a1b",
    "service_id": "6af9a1b2c3d4e5f6a7b8c9d0",
    "service_name": "Limpieza dental",
    "collaborator_id": "6af9a1b2c3d4e5f6a7b8c9d1",
    "collaborator_name": "Geral Díaz",
    "start": "2026-11-21T14:00:00.000Z",
    "end": "2026-11-21T14:45:00.000Z",
    "status": "CANCELLED",
    "contact_id": "6ac9f1e6af6d42a269f21b15",
    "contact_name": "Ana Gómez",
    "phone": "+573001234567",
    "external_id": null,
    "order_id": "6b1d2e3f4a5b6c7d8e9f0a1c"
  }
}
json
{
  "id": "evt_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
  "type": "order.paid",
  "created_at": "2026-11-19T15:10:42.000Z",
  "agent_id": "66a54f2f2281f02197cb21bd",
  "data": {
    "order_id": "6b1d2e3f4a5b6c7d8e9f0a1c",
    "status": "PAID",
    "total": 180000,
    "currency": "COP",
    "payment_method": "wompi",
    "contact_id": "6ac9f1e6af6d42a269f21b15",
    "contact_name": "Ana Gómez",
    "phone": "+573001234567",
    "external_id": null
  }
}
json
{
  "id": "evt_9f8e7d6c5b4a39281706f5e4d3c2b1a0",
  "type": "escalation.created",
  "created_at": "2026-11-19T15:20:03.000Z",
  "agent_id": "66a54f2f2281f02197cb21bd",
  "data": {
    "trigger": "cliente",
    "contact_id": "6ac9f1e6af6d42a269f21b15",
    "contact_name": "Ana Gómez",
    "phone": "+573001234567",
    "reason": "Pide hablar con una persona sobre un cobro",
    "message": "¿Me puede atender alguien? Me cobraron dos veces"
  }
}
json
{
  "id": "evt_0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d",
  "type": "webhook.test",
  "created_at": "2026-11-19T15:00:00.000Z",
  "agent_id": "66a54f2f2281f02197cb21bd",
  "data": {
    "webhook_id": "6b1d2e3f4a5b6c7d8e9f0a2d",
    "message": "Prueba de TBit: si ves esto, tu endpoint recibe y puede verificar la firma."
  }
}
HeaderValeur
Content-Typeapplication/json
TBit-EventLe type d'événement, par exemple appointment.created
TBit-DeliveryL'id de la livraison. Il est identique à chaque nouvelle tentative de cette livraison.
TBit-Signaturet=<unix>,v1=<hex> : la signature, voir ci-dessous
User-AgentTBit-Webhooks/1.0

TBit signe chaque livraison avec le secret du webhook (HMAC-SHA256), à la manière de Stripe. Le header TBit-Signature contient t (l'heure unix de l'envoi) et v1 (la signature en hex). Pour vérifier :

  1. Prenez le corps BRUT de la requête, les octets exacts, sans réanalyser ni réordonner le JSON.
  2. Composez le texte <t>.<cuerpo> et calculez HMAC-SHA256 avec votre secret (whsec_…, complet).
  3. Comparez avec v1 en temps constant. Si cela ne correspond pas, répondez 400 et ignorez.
  4. Rejetez celles qui ont t à plus de 5 minutes de votre heure, pour que personne ne vous renvoie une livraison ancienne.
javascript
import crypto from "node:crypto";
import express from "express";

const SECRET = process.env.TBIT_WEBHOOK_SECRET; // whsec_…
const TOLERANCE_SECONDS = 300;

function verify(rawBody, header) {
  const parts = Object.fromEntries(
    (header || "").split(",").map((p) => p.split("=").map((s) => s.trim())),
  );
  const t = Number(parts.t);
  const v1 = parts.v1;
  if (!t || !v1) return false;
  if (Math.abs(Date.now() / 1000 - t) > TOLERANCE_SECONDS) return false;
  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(`${t}.${rawBody}`, "utf8")
    .digest("hex");
  return (
    expected.length === v1.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1))
  );
}

const app = express();
// El cuerpo CRUDO: la firma es sobre los bytes exactos, no sobre el JSON reparseado.
app.post("/webhooks/tbit", express.raw({ type: "application/json" }), (req, res) => {
  const raw = req.body.toString("utf8");
  if (!verify(raw, req.get("TBit-Signature"))) return res.sendStatus(400);
  const event = JSON.parse(raw);
  // Responde rápido y procesa aparte; deduplica por event.id.
  res.sendStatus(200);
  console.log(event.type, event.data);
});

app.listen(3000);
python
import hashlib
import hmac
import json
import os
import time

from flask import Flask, abort, request

SECRET = os.environ["TBIT_WEBHOOK_SECRET"]  # whsec_…
TOLERANCE_SECONDS = 300

app = Flask(__name__)


def verify(raw_body: bytes, header: str) -> bool:
    parts = dict(p.strip().split("=", 1) for p in (header or "").split(",") if "=" in p)
    try:
        t = int(parts["t"])
        v1 = parts["v1"]
    except (KeyError, ValueError):
        return False
    if abs(time.time() - t) > TOLERANCE_SECONDS:
        return False
    signed = f"{t}.".encode() + raw_body
    expected = hmac.new(SECRET.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)


@app.post("/webhooks/tbit")
def tbit_webhook():
    raw = request.get_data()  # los bytes exactos que firmó TBit
    if not verify(raw, request.headers.get("TBit-Signature", "")):
        abort(400)
    event = json.loads(raw)
    # Responde rápido y procesa aparte; deduplica por event["id"].
    print(event["type"], event["data"])
    return "", 200

Une livraison est considérée comme livrée lorsque votre système répond 2xx en moins de 10 secondes. Un 3xx n'est pas suivi (compte comme un échec), tout comme un 4xx, un 5xx, un timeout ou une erreur réseau. En cas d'échec, TBit réessaie avec cette attente :

TentativeAttente depuis la précédente
21 minute
35 minutes
430 minutes
52 heures
66 heures
724 heures

Après la septième tentative, la livraison est failed. Si 20 livraisons consécutives échouent, TBit désactive le webhook (status: disabled, disabled_reason: failure_streak) et envoie un e-mail aux administrateurs de l'agent. Pour le réactiver, corrigez votre système, vérifiez avec POST /v1/webhooks/{id}/test et envoyez PATCH {"status": "active"}. Les événements survenus pendant la désactivation ne sont pas envoyés après.

CodeQuand
400 VALIDATION_ERRORURL qui n'est pas https, privée ou interne ; événement inconnu ; rien à modifier.
404 NOT_FOUNDLe webhook n'existe pas dans cet agent.
409 LIMIT_REACHEDL'agent a déjà 10 webhooks.
429 RATE_LIMITEDPlus de 20 tests par minute.