# Webhooks

> Informiere dein System sofort und signiert, wenn in deinem Agenten etwas passiert

- Seite: https://tbit.app/de/docs/api/webhooks
- Basis-URL: `https://rest-api.tbit.app/v1`
- Authentifizierung: Header `X-API-Key` mit deinem Schlüssel in jeder Anfrage (die Beispiele lesen ihn aus der Umgebungsvariable `TBIT_API_KEY`)

## Übersicht

Ein Webhook ist eine URL deines Systems, an die TBit jedes Mal einen signierten POST schickt, wenn in deinem Agenten etwas passiert: ein Termin wird geplant, verschoben oder abgesagt, eine Bestellung wird bezahlt oder die KI übergibt eine Konversation an das Team. So erfahren dein Kalender, dein ERP oder dein CRM davon, ohne nachfragen zu müssen.

Webhooks werden hier über die API, in der App (Plugins › Entwicklung › Webhooks) oder über den MCP mit `manage_webhooks` erstellt. Alle drei Wege nutzen dieselben Namen: `url`, `events`, `description` und `status`. Bis zu 10 pro Agent.

## Endpunkte

| Methode | Pfad | Beschreibung |
| --- | --- | --- |
| `GET` | `/v1/webhooks` | Listet die Webhooks auf, jeder mit seinen letzten 5 Zustellungen |
| `POST` | `/v1/webhooks` | Erstellt einen Webhook; gibt das Secret nur einmal zurück |
| `GET` | `/v1/webhooks/{id}` | Ein Webhook mit seinen letzten Zustellungen (?limit= bis 100) |
| `PATCH` | `/v1/webhooks/{id}` | Ändert url, events, description oder status |
| `DELETE` | `/v1/webhooks/{id}` | Löscht den Webhook |
| `POST` | `/v1/webhooks/{id}/test` | Schickt sofort ein signiertes webhook.test-Event und gibt zurück, was dein System geantwortet hat |

## Einen Webhook erstellen

Felder: `url` (https und öffentlich: private IPs, localhost und interne Adressen werden nicht akzeptiert), `events` (mindestens eines aus der Event-Tabelle) und `description` (optional, bis 200 Zeichen). Die Antwort enthält `secret`: speichere es, es erscheint nur dieses eine Mal und damit verifizierst du jede Zustellung.

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

Antwort:

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

## Zustellungen auflisten und ansehen

Jeder Webhook enthält `recent_deliveries`: das Event, den Status (`delivered`, `pending` oder `failed`), die Versuche, den HTTP-Code, den dein System geantwortet hat, und wie lange es gedauert hat. Zustellungen werden 30 Tage aufbewahrt.

`GET /v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d`

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

Antwort:

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

## Ändern, ausschalten oder löschen

Schicke nur, was sich ändert. `"status": "disabled"` schaltet den Webhook aus, ohne ihn zu löschen; `"status": "active"` schaltet ihn wieder ein und setzt den Fehlerzähler auf null (so wird einer reaktiviert, den TBit ausgeschaltet hat).

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

## Eine Testnachricht senden

Schickt sofort ein `webhook.test`-Event, signiert mit dem Secret des Webhooks, auch wenn er ausgeschaltet ist und auch wenn er auf nichts abonniert ist, und sagt dir, was dein System geantwortet hat. Zählt nicht als Fehler für das automatische Ausschalten. Limit: 20 pro 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"
```

Antwort:

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

## Events

| Ereignis | Wann es ausgelöst wird |
| --- | --- |
| `appointment.created` | Ein Termin wurde gebucht (durch die KI, das Team in der App, das MCP oder die API). |
| `appointment.rescheduled` | Ein Termin hat Datum oder Uhrzeit geändert. Jede Änderung ist ein Ereignis. |
| `appointment.cancelled` | Ein Termin wurde storniert (auch wenn er aus dem verbundenen Google Calendar gelöscht wird). |
| `order.paid` | Eine Bestellung wurde bezahlt. |
| `escalation.created` | Die KI hat eine Unterhaltung an das Team übergeben (Eskalation). |
| `webhook.test` | Nur mit „Test senden“. Wird nicht abonniert. |

Buchungen von Ressourcen, die vermietet werden (Zimmer, Säle, Fahrzeuge), erscheinen noch nicht als `appointment.*`. Das Ereignis für neue Kontakte kommt in einer kommenden Version.

## Der Umschlag

Alle Zustellungen haben dieselbe Form: `id` (einmalig pro Ereignis: nutze es, um nicht zweimal zu verarbeiten), `type`, `created_at` (ISO 8601, UTC), `agent_id` und `data`, mit flachen Feldern. Die Daten sind in UTC; ein Feld ohne Wert kommt als `null`.

### appointment.rescheduled

Dieselben Felder, mit der neuen Zeit in `start` und `end`.

### escalation.created

`trigger` sagt, wer es ausgelöst hat: `cliente` (hat es angefordert), `bot` (die KI hat es dem Team überlassen), `energy_blocked` (TBit hat wegen fehlender Energie nicht geantwortet) oder `bot_guard` (es sah nach einem automatischen System aus).

```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 | Wert |
| --- | --- |
| `Content-Type` | `application/json` |
| `TBit-Event` | Der Ereignistyp, zum Beispiel `appointment.created` |
| `TBit-Delivery` | Die ID der Zustellung. Sie ist bei jedem erneuten Versuch dieser Zustellung gleich. |
| `TBit-Signature` | `t=<unix>,v1=<hex>`: die Signatur, siehe unten |
| `User-Agent` | `TBit-Webhooks/1.0` |

## Die Signatur prüfen

TBit signiert jede Zustellung mit dem Secret des Webhooks (HMAC-SHA256), im Stil von Stripe. Der Header `TBit-Signature` enthält `t` (die Unix-Zeit des Versands) und `v1` (die Signatur in Hex). Zum Prüfen:

1. Nimm den ROHEN Body der Anfrage, die exakten Bytes, ohne das JSON neu zu parsen oder umzusortieren.
2. Baue den Text `<t>.<cuerpo>` und berechne HMAC-SHA256 mit deinem Secret (`whsec_…`, vollständig).
3. Vergleiche mit `v1` in konstanter Zeit. Wenn es nicht übereinstimmt, antworte mit 400 und verwerfe.
4. Lehne die ab, die `t` mehr als 5 Minuten von deiner Uhrzeit entfernt haben, damit dir niemand eine alte Zustellung erneut schickt.

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

## Wiederholungen und automatisches Abschalten

Eine Zustellung gilt als zugestellt, wenn dein System mit 2xx in weniger als 10 Sekunden antwortet. Einem 3xx wird nicht gefolgt (zählt als Fehler), genauso wie einem 4xx, einem 5xx, einem Timeout oder einem Netzwerkfehler. Wenn es fehlschlägt, versucht TBit es mit dieser Wartezeit erneut:

| Versuch | Wartezeit seit dem vorherigen |
| --- | --- |
| 2 | 1 Minute |
| 3 | 5 Minuten |
| 4 | 30 Minuten |
| 5 | 2 Stunden |
| 6 | 6 Stunden |
| 7 | 24 Stunden |

Nach dem siebten Versuch bleibt die Zustellung `failed`. Wenn 20 Zustellungen in Folge fehlschlagen, schaltet TBit den Webhook ab (`status: disabled`, `disabled_reason: failure_streak`) und schreibt den Administratoren des Agenten eine E-Mail. Um ihn wieder zu aktivieren, repariere dein System, prüfe mit `POST /v1/webhooks/{id}/test` und sende `PATCH {"status": "active"}`. Ereignisse, die während der Abschaltung passiert sind, werden danach nicht nachgesendet.

> **Bewährte Praktiken**
>
> - Antworte mit 2xx, sobald du empfangen und verifiziert hast, und verarbeite getrennt: wenn du länger als 10 Sekunden brauchst, zählt es als Fehler und wird erneut versucht.
> - Die Zustellung erfolgt mindestens einmal: dasselbe Ereignis kann zweimal ankommen. Dedupliziere nach `id`.
> - Die Reihenfolge ist nicht garantiert: verwende `created_at` und frage bei Bedarf den aktuellen Status ab.

## Fehler

| Code | Wann |
| --- | --- |
| `400 VALIDATION_ERROR` | URL, die nicht https, privat oder intern ist; unbekanntes Ereignis; nichts zu ändern. |
| `404 NOT_FOUND` | Der Webhook existiert bei diesem Agenten nicht. |
| `409 LIMIT_REACHED` | Der Agent hat bereits 10 Webhooks. |
| `429 RATE_LIMITED` | Mehr als 20 Tests pro Minute. |
