# Webhooks

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

- Page: https://tbit.app/fr/docs/api/webhooks
- URL de base: `https://rest-api.tbit.app/v1`
- Authentification: en-tête `X-API-Key` avec votre clé dans chaque requête (les exemples la lisent depuis la variable d'environnement `TBIT_API_KEY`)

## Description générale

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.

## Endpoints

| Méthode | Route | Description |
| --- | --- | --- |
| `GET` | `/v1/webhooks` | Liste les webhooks, chacun avec ses 5 dernières livraisons |
| `POST` | `/v1/webhooks` | Cré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}/test` | Envoie 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`

```bash
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"
  }'
```

Réponse:

```json
{
  "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)"
  }
}
```

## Lister et voir les livraisons

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`

```bash
curl "https://rest-api.tbit.app/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d?limit=20" \
  -H "X-API-Key: $TBIT_API_KEY"
```

Réponse:

```json
{
  "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
        }
      ]
    }
  }
}
```

## Modifier, désactiver ou supprimer

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`

```bash
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"
  }'
```

`DELETE /v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d`

```bash
curl -X DELETE "https://rest-api.tbit.app/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d" \
  -H "X-API-Key: $TBIT_API_KEY"
```

## 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`

```bash
curl -X POST "https://rest-api.tbit.app/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d/test" \
  -H "X-API-Key: $TBIT_API_KEY"
```

Réponse:

```json
{
  "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énements

| Événement | Quand il se produit |
| --- | --- |
| `appointment.created` | Un rendez-vous a été planifié (par l'IA, l'équipe dans l'app, le MCP ou l'API). |
| `appointment.rescheduled` | Un rendez-vous a changé de date ou d'heure. Chaque changement est un événement. |
| `appointment.cancelled` | Un rendez-vous a été annulé (y compris s'il est supprimé du Google Calendar connecté). |
| `order.paid` | Une commande a été payée. |
| `escalation.created` | L'IA a transmis une conversation à l'équipe (escalade). |
| `webhook.test` | Uniquement 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.

## L'enveloppe

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."
  }
}
```

## Headers

| Header | Valeur |
| --- | --- |
| `Content-Type` | `application/json` |
| `TBit-Event` | Le type d'événement, par exemple `appointment.created` |
| `TBit-Delivery` | L'id de la livraison. Il est identique à chaque nouvelle tentative de cette livraison. |
| `TBit-Signature` | `t=<unix>,v1=<hex>` : la signature, voir ci-dessous |
| `User-Agent` | `TBit-Webhooks/1.0` |

## Vérifier la signature

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
```

## Nouvelles tentatives et désactivation automatique

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 :

| Tentative | Attente depuis la précédente |
| --- | --- |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 heures |
| 6 | 6 heures |
| 7 | 24 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.

> **Bonnes pratiques**
>
> - Répondez 2xx dès réception et vérification, puis traitez à part : si vous mettez plus de 10 secondes, cela compte comme un échec et une nouvelle tentative est faite.
> - La livraison est au moins une fois : le même événement peut arriver deux fois. Dédupliquez par `id`.
> - L'ordre n'est pas garanti : utilisez `created_at` et, si nécessaire, consultez l'état actuel.

## Erreurs

| Code | Quand |
| --- | --- |
| `400 VALIDATION_ERROR` | URL qui n'est pas https, privée ou interne ; événement inconnu ; rien à modifier. |
| `404 NOT_FOUND` | Le webhook n'existe pas dans cet agent. |
| `409 LIMIT_REACHED` | L'agent a déjà 10 webhooks. |
| `429 RATE_LIMITED` | Plus de 20 tests par minute. |
