API
Webhooks
Laat je systeem meteen en ondertekend weten wanneer er iets gebeurt in je agent
# Webhooks > Laat je systeem meteen en ondertekend weten wanneer er iets gebeurt in je agent - Pagina: https://tbit.app/nl/docs/api/webhooks - Basis-URL: `https://rest-api.tbit.app/v1` - Authenticatie: header `X-API-Key` met je sleutel bij elk verzoek (de voorbeelden lezen hem uit de omgevingsvariabele `TBIT_API_KEY`) ## Overzicht Een webhook is een URL van jouw systeem waar TBit een ondertekende POST naartoe stuurt telkens wanneer er iets gebeurt in je agent: een afspraak wordt ingepland, verplaatst of geannuleerd, een bestelling wordt betaald of de AI geeft een gesprek door aan het team. Zo weten je agenda, je ERP of je CRM het zonder te hoeven vragen. Webhooks maak je hier met de API, in de app (Plugins › Ontwikkeling › Webhooks) of vanuit de MCP met `manage_webhooks`. De drie ingangen gebruiken dezelfde namen: `url`, `events`, `description` en `status`. Maximaal 10 per agent. ## Endpoints | Methode | Pad | Beschrijving | | --- | --- | --- | | `GET` | `/v1/webhooks` | Geeft de webhooks weer, elk met de laatste 5 leveringen | | `POST` | `/v1/webhooks` | Maakt een webhook aan; geeft het geheim één keer terug | | `GET` | `/v1/webhooks/{id}` | Een webhook met de laatste leveringen (?limit= tot 100) | | `PATCH` | `/v1/webhooks/{id}` | Wijzigt url, events, description of status | | `DELETE` | `/v1/webhooks/{id}` | Verwijdert de webhook | | `POST` | `/v1/webhooks/{id}/test` | Stuurt meteen een ondertekend webhook.test-event en geeft terug wat je systeem antwoordde | ## Een webhook aanmaken Velden: `url` (https en openbaar: privé-IP's, localhost en interne adressen worden niet geaccepteerd), `events` (minstens één uit de tabel met gebeurtenissen) en `description` (optioneel, tot 200 tekens). Het antwoord bevat `secret`: bewaar het, het komt maar één keer naar buiten en ermee verifieer je elke levering. `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" }' ``` Response: ```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)" } } ``` ## Leveringen weergeven en bekijken Elke webhook bevat `recent_deliveries`: de gebeurtenis, de status (`delivered`, `pending` of `failed`), de pogingen, de HTTP-code die je systeem antwoordde en hoe lang het duurde. Leveringen worden 30 dagen bewaard. `GET /v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d` ```bash curl "https://rest-api.tbit.app/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d?limit=20" \ -H "X-API-Key: $TBIT_API_KEY" ``` Response: ```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 } ] } } } ``` ## Wijzigen, uitzetten of verwijderen Stuur alleen wat verandert. `"status": "disabled"` zet de webhook uit zonder hem te verwijderen; `"status": "active"` zet hem weer aan en zet de teller van mislukkingen op nul (zo reactiveer je er een die TBit heeft uitgezet). `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" ``` ## Een test sturen Stuurt meteen een `webhook.test`-gebeurtenis ondertekend met het geheim van de webhook, ook als hij uit staat en nergens op is geabonneerd, en vertelt je wat je systeem antwoordde. Telt niet als mislukking voor het automatisch uitzetten. Limiet: 20 per minuut. `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" ``` Response: ```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." } } ``` ## Gebeurtenissen | Gebeurtenis | Wanneer het afgaat | | --- | --- | | `appointment.created` | Er is een afspraak ingepland (door de AI, het team in de app, de MCP of de API). | | `appointment.rescheduled` | Een afspraak is van datum of tijd veranderd. Elke wijziging is een gebeurtenis. | | `appointment.cancelled` | Een afspraak is geannuleerd (ook als ze hem uit de gekoppelde Google Calendar verwijderen). | | `order.paid` | Een bestelling is betaald. | | `escalation.created` | De AI heeft een gesprek aan het team doorgegeven (escalatie). | | `webhook.test` | Alleen met «Test verzenden». Wordt niet geabonneerd. | Reserveringen van resources die je verhuurt (kamers, zalen, voertuigen) komen nog niet als `appointment.*`. De gebeurtenis voor een nieuwe contact komt in een volgende versie. ## De envelop Alle leveringen hebben dezelfde vorm: `id` (uniek per gebeurtenis: gebruik het om niet twee keer te verwerken), `type`, `created_at` (ISO 8601, UTC), `agent_id` en `data`, met platte velden. Datums staan in UTC; een veld zonder waarde komt als `null`. ### appointment.rescheduled Dezelfde velden, met de nieuwe tijd in `start` en `end`. ### escalation.created `trigger` zegt wie het heeft veroorzaakt: `cliente` (vroeg erom), `bot` (de AI liet het aan het team over), `energy_blocked` (TBit antwoordde niet door gebrek aan energie) of `bot_guard` (leek een automatisch systeem). ```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 | Waarde | | --- | --- | | `Content-Type` | `application/json` | | `TBit-Event` | Het type gebeurtenis, bijvoorbeeld `appointment.created` | | `TBit-Delivery` | Het id van de levering. Het is hetzelfde bij elke nieuwe poging van die levering. | | `TBit-Signature` | `t=<unix>,v1=<hex>`: de handtekening, zie hieronder | | `User-Agent` | `TBit-Webhooks/1.0` | ## De handtekening verifiëren TBit ondertekent elke levering met het geheim van de webhook (HMAC-SHA256), zoals bij Stripe. De header `TBit-Signature` bevat `t` (de unixtijd van het verzenden) en `v1` (de handtekening in hex). Om te verifiëren: 1. Neem de RAUWE body van het verzoek, de exacte bytes, zonder de JSON opnieuw te parsen of te herordenen. 2. Bouw de tekst `<t>.<cuerpo>` en bereken HMAC-SHA256 met je secret (`whsec_…`, volledig). 3. Vergelijk met `v1` in constante tijd. Als het niet overeenkomt, antwoord 400 en gooi het weg. 4. Weiger degenen met `t` meer dan 5 minuten van je tijd, zodat niemand een oude levering naar je doorstuurt. ```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 ``` ## Nieuwe pogingen en automatische uitschakeling Een levering telt als geleverd wanneer je systeem binnen 10 seconden met 2xx antwoordt. Een 3xx wordt niet gevolgd (telt als fout), net als een 4xx, een 5xx, een timeout of een netwerkfout. Als het mislukt, probeert TBit opnieuw met deze wachttijd: | Poging | Wachttijd sinds de vorige | | --- | --- | | 2 | 1 minuut | | 3 | 5 minuten | | 4 | 30 minuten | | 5 | 2 uur | | 6 | 6 uur | | 7 | 24 uur | Na de zevende poging is de levering `failed`. Als 20 leveringen achter elkaar mislukken, schakelt TBit de webhook uit (`status: disabled`, `disabled_reason: failure_streak`) en stuurt een e-mail naar de beheerders van de agent. Om hem weer te activeren, herstel je systeem, controleer je met `POST /v1/webhooks/{id}/test` en stuur je `PATCH {"status": "active"}`. Gebeurtenissen die plaatsvonden terwijl hij uitgeschakeld was, worden daarna niet verstuurd. > **Goede praktijken** > > - Antwoord 2xx zodra je ontvangt en verifieert, en verwerk apart: als je langer dan 10 seconden doet, telt het als fout en wordt het opnieuw geprobeerd. > - De levering is minstens één keer: dezelfde gebeurtenis kan twee keer aankomen. Dedupliceer op `id`. > - De volgorde is niet gegarandeerd: gebruik `created_at` en raadpleeg indien nodig de huidige status. ## Fouten | Code | Wanneer | | --- | --- | | `400 VALIDATION_ERROR` | URL die geen https is, privé of intern; onbekende gebeurtenis; niets om te wijzigen. | | `404 NOT_FOUND` | De webhook bestaat niet bij deze agent. | | `409 LIMIT_REACHED` | De agent heeft al 10 webhooks. | | `429 RATE_LIMITED` | Meer dan 20 tests per minuut. |Een webhook is een URL van jouw systeem waar TBit een ondertekende POST naartoe stuurt telkens wanneer er iets gebeurt in je agent: een afspraak wordt ingepland, verplaatst of geannuleerd, een bestelling wordt betaald of de AI geeft een gesprek door aan het team. Zo weten je agenda, je ERP of je CRM het zonder te hoeven vragen.
Webhooks maak je hier met de API, in de app (Plugins › Ontwikkeling › Webhooks) of vanuit de MCP met manage_webhooks. De drie ingangen gebruiken dezelfde namen: url, events, description en status. Maximaal 10 per agent.
| Methode | Pad | Beschrijving |
|---|---|---|
| GET | /v1/webhooks | Geeft de webhooks weer, elk met de laatste 5 leveringen |
| POST | /v1/webhooks | Maakt een webhook aan; geeft het geheim één keer terug |
| GET | /v1/webhooks/{id} | Een webhook met de laatste leveringen (?limit= tot 100) |
| PATCH | /v1/webhooks/{id} | Wijzigt url, events, description of status |
| DELETE | /v1/webhooks/{id} | Verwijdert de webhook |
| POST | /v1/webhooks/{id}/test | Stuurt meteen een ondertekend webhook.test-event en geeft terug wat je systeem antwoordde |
Velden: url (https en openbaar: privé-IP's, localhost en interne adressen worden niet geaccepteerd), events (minstens één uit de tabel met gebeurtenissen) en description (optioneel, tot 200 tekens). Het antwoord bevat secret: bewaar het, het komt maar één keer naar buiten en ermee verifieer je elke levering.
/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)"
}
}Elke webhook bevat recent_deliveries: de gebeurtenis, de status (delivered, pending of failed), de pogingen, de HTTP-code die je systeem antwoordde en hoe lang het duurde. Leveringen worden 30 dagen bewaard.
/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
}
]
}
}
}Stuur alleen wat verandert. "status": "disabled" zet de webhook uit zonder hem te verwijderen; "status": "active" zet hem weer aan en zet de teller van mislukkingen op nul (zo reactiveer je er een die TBit heeft uitgezet).
/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);Stuurt meteen een webhook.test-gebeurtenis ondertekend met het geheim van de webhook, ook als hij uit staat en nergens op is geabonneerd, en vertelt je wat je systeem antwoordde. Telt niet als mislukking voor het automatisch uitzetten. Limiet: 20 per minuut.
/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."
}
}| Gebeurtenis | Wanneer het afgaat |
|---|---|
appointment.created | Er is een afspraak ingepland (door de AI, het team in de app, de MCP of de API). |
appointment.rescheduled | Een afspraak is van datum of tijd veranderd. Elke wijziging is een gebeurtenis. |
appointment.cancelled | Een afspraak is geannuleerd (ook als ze hem uit de gekoppelde Google Calendar verwijderen). |
order.paid | Een bestelling is betaald. |
escalation.created | De AI heeft een gesprek aan het team doorgegeven (escalatie). |
webhook.test | Alleen met «Test verzenden». Wordt niet geabonneerd. |
Reserveringen van resources die je verhuurt (kamers, zalen, voertuigen) komen nog niet als appointment.*. De gebeurtenis voor een nieuwe contact komt in een volgende versie.
Alle leveringen hebben dezelfde vorm: id (uniek per gebeurtenis: gebruik het om niet twee keer te verwerken), type, created_at (ISO 8601, UTC), agent_id en data, met platte velden. Datums staan in UTC; een veld zonder waarde komt als null.
appointment.rescheduled
Dezelfde velden, met de nieuwe tijd in start en end.
escalation.created
trigger zegt wie het heeft veroorzaakt: cliente (vroeg erom), bot (de AI liet het aan het team over), energy_blocked (TBit antwoordde niet door gebrek aan energie) of bot_guard (leek een automatisch systeem).
{
"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 | Waarde |
|---|---|
Content-Type | application/json |
TBit-Event | Het type gebeurtenis, bijvoorbeeld appointment.created |
TBit-Delivery | Het id van de levering. Het is hetzelfde bij elke nieuwe poging van die levering. |
TBit-Signature | t=<unix>,v1=<hex>: de handtekening, zie hieronder |
User-Agent | TBit-Webhooks/1.0 |
TBit ondertekent elke levering met het geheim van de webhook (HMAC-SHA256), zoals bij Stripe. De header TBit-Signature bevat t (de unixtijd van het verzenden) en v1 (de handtekening in hex). Om te verifiëren:
- Neem de RAUWE body van het verzoek, de exacte bytes, zonder de JSON opnieuw te parsen of te herordenen.
- Bouw de tekst
<t>.<cuerpo>en bereken HMAC-SHA256 met je secret (whsec_…, volledig). - Vergelijk met
v1in constante tijd. Als het niet overeenkomt, antwoord 400 en gooi het weg. - Weiger degenen met
tmeer dan 5 minuten van je tijd, zodat niemand een oude levering naar je doorstuurt.
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 "", 200Een levering telt als geleverd wanneer je systeem binnen 10 seconden met 2xx antwoordt. Een 3xx wordt niet gevolgd (telt als fout), net als een 4xx, een 5xx, een timeout of een netwerkfout. Als het mislukt, probeert TBit opnieuw met deze wachttijd:
| Poging | Wachttijd sinds de vorige |
|---|---|
| 2 | 1 minuut |
| 3 | 5 minuten |
| 4 | 30 minuten |
| 5 | 2 uur |
| 6 | 6 uur |
| 7 | 24 uur |
Na de zevende poging is de levering failed. Als 20 leveringen achter elkaar mislukken, schakelt TBit de webhook uit (status: disabled, disabled_reason: failure_streak) en stuurt een e-mail naar de beheerders van de agent. Om hem weer te activeren, herstel je systeem, controleer je met POST /v1/webhooks/{id}/test en stuur je PATCH {"status": "active"}. Gebeurtenissen die plaatsvonden terwijl hij uitgeschakeld was, worden daarna niet verstuurd.
| Code | Wanneer |
|---|---|
400 VALIDATION_ERROR | URL die geen https is, privé of intern; onbekende gebeurtenis; niets om te wijzigen. |
404 NOT_FOUND | De webhook bestaat niet bij deze agent. |
409 LIMIT_REACHED | De agent heeft al 10 webhooks. |
429 RATE_LIMITED | Meer dan 20 tests per minuut. |