API
Webhooks
Informiere dein System sofort und signiert, wenn in deinem Agenten etwas passiert
# 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. |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.
| 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 |
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.
/v1/webhookscurl -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);{
"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)"
}
}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.
/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2dcurl "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);{
"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
}
]
}
}
}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).
/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2dcurl -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);/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2dcurl -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);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.
/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d/testcurl -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);{
"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."
}
}| 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.
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).
{
"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"
}
}{
"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"
}
}{
"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"
}
}{
"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
}
}{
"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"
}
}{
"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."
}
}| 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 |
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:
- Nimm den ROHEN Body der Anfrage, die exakten Bytes, ohne das JSON neu zu parsen oder umzusortieren.
- Baue den Text
<t>.<cuerpo>und berechne HMAC-SHA256 mit deinem Secret (whsec_…, vollständig). - Vergleiche mit
v1in konstanter Zeit. Wenn es nicht übereinstimmt, antworte mit 400 und verwerfe. - Lehne die ab, die
tmehr als 5 Minuten von deiner Uhrzeit entfernt haben, damit dir niemand eine alte Zustellung erneut schickt.
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);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 "", 200Eine 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.
| 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. |