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