Vai al contenuto
Menu

Cerca nel sito

Scrivi per cercare tra guide, blog, API e prodotto.

↑ ↓ per spostarti · Invio per aprire · Esc per chiudere

Riferimento dell'API

API

Webhook

Avvisa il tuo sistema, all'istante e firmato, quando succede qualcosa nel tuo agente

Vedi come Markdown

Un webhook è un URL del tuo sistema a cui TBit fa un POST firmato ogni volta che succede qualcosa nel tuo agente: un appuntamento viene fissato, riprogrammato o annullato, un ordine viene pagato o l'IA passa una conversazione al team. Così la tua agenda, il tuo ERP o il tuo CRM lo sanno senza dover chiedere.

I webhook si creano qui con l'API, nell'app (Plugin › Sviluppo › Webhook) o dal MCP con manage_webhooks. Le tre porte usano gli stessi nomi: url, events, description e status. Fino a 10 per agente.

MetodoPercorsoDescrizione
GET/v1/webhooksElenca i webhook, ognuno con le sue ultime 5 consegne
POST/v1/webhooksCrea un webhook; restituisce il segreto una sola volta
GET/v1/webhooks/{id}Un webhook con le sue ultime consegne (?limit= fino a 100)
PATCH/v1/webhooks/{id}Cambia url, events, description o status
DELETE/v1/webhooks/{id}Elimina il webhook
POST/v1/webhooks/{id}/testInvia subito un evento webhook.test firmato e restituisce cosa ha risposto il tuo sistema

Creare un webhook

Campi: url (https e pubblico: non si accettano IP privati, localhost né indirizzi interni), events (almeno uno dalla tabella degli eventi) e description (opzionale, fino a 200 caratteri). La risposta contiene secret: salvalo, è l'unica volta che esce e con esso verifichi ogni consegna.

POST/v1/webhooks
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"
  }'
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);
Risposta
{
  "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)"
  }
}

Ogni webhook contiene recent_deliveries: l'evento, lo stato (delivered, pending o failed), i tentativi, il codice HTTP che ha risposto il tuo sistema e quanto ci ha messo. Le consegne si conservano 30 giorni.

GET/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d
curl "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);
Risposta
{
  "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
        }
      ]
    }
  }
}

Invia solo ciò che cambia. "status": "disabled" spegne il webhook senza eliminarlo; "status": "active" lo riaccende e azzera il conteggio dei fallimenti (così si riattiva uno che TBit ha spento).

PATCH/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d
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"
  }'
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);
DELETE/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d
curl -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);

Inviare una prova

Invia all'istante un evento webhook.test firmato con il segreto del webhook, anche se è spento e anche se non è iscritto a nulla, e ti dice cosa ha risposto il tuo sistema. Non conta come fallimento per lo spegnimento automatico. Limite: 20 al minuto.

POST/v1/webhooks/6b1d2e3f4a5b6c7d8e9f0a2d/test
curl -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);
Risposta
{
  "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."
  }
}
EventoQuando arriva
appointment.createdÈ stato fissato un appuntamento (l'IA, il team nell'app, l'MCP o l'API).
appointment.rescheduledUn appuntamento ha cambiato data o ora. Ogni modifica è un evento.
appointment.cancelledUn appuntamento è stato annullato (anche se lo eliminano dal Google Calendar collegato).
order.paidUn ordine è stato pagato.
escalation.createdL'IA ha passato una conversazione al team (escalation).
webhook.testSolo con «Invia prova». Non si sottoscrive.

Le prenotazioni di risorse a noleggio (camere, sale, veicoli) non arrivano ancora come appointment.*. L'evento di nuovo contatto arriverà in una prossima versione.

Tutte le consegne hanno la stessa forma: id (unico per evento: usalo per non elaborare due volte), type, created_at (ISO 8601, UTC), agent_id e data, con campi piatti. Le date vanno in UTC; un campo senza valore arriva in null.

appointment.rescheduled

Gli stessi campi, con la nuova ora in start e end.

escalation.created

trigger dice chi lo ha provocato: cliente (lo ha richiesto), bot (l'IA lo ha lasciato al team), energy_blocked (TBit non ha risposto per mancanza di energia) o bot_guard (sembrava un sistema automatico).

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."
  }
}
HeaderValore
Content-Typeapplication/json
TBit-EventIl tipo di evento, per esempio appointment.created
TBit-DeliveryL'id della consegna. È lo stesso in ogni nuovo tentativo di quella consegna.
TBit-Signaturet=<unix>,v1=<hex>: la firma, vedi sotto
User-AgentTBit-Webhooks/1.0

TBit firma ogni consegna con il segreto del webhook (HMAC-SHA256), nello stile di Stripe. L'header TBit-Signature contiene t (l'ora unix dell'invio) e v1 (la firma in hex). Per verificare:

  1. Prendi il corpo GREZZO della richiesta, i byte esatti, senza riparsare né riordinare il JSON.
  2. Componi il testo <t>.<cuerpo> e calcola HMAC-SHA256 con il tuo segreto (whsec_…, completo).
  3. Confronta con v1 in tempo costante. Se non coincide, rispondi 400 e scarta.
  4. Rifiuta quelle che hanno t a più di 5 minuti dalla tua ora, così nessuno ti reinvia una consegna vecchia.
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

Una consegna conta come consegnata quando il tuo sistema risponde 2xx in meno di 10 secondi. Un 3xx non viene seguito (conta come errore), così come un 4xx, un 5xx, un timeout o un errore di rete. Se fallisce, TBit riprova con questa attesa:

TentativoAttesa dal precedente
21 minuto
35 minuti
430 minuti
52 ore
66 ore
724 ore

Dopo il settimo tentativo la consegna resta failed. Se 20 consegne di seguito terminano fallite, TBit spegne il webhook (status: disabled, disabled_reason: failure_streak) e scrive un'email agli amministratori dell'agente. Per riattivarlo, sistema il tuo sistema, verifica con POST /v1/webhooks/{id}/test e invia PATCH {"status": "active"}. Gli eventi accaduti mentre era spento non vengono inviati dopo.

CodiceQuando
400 VALIDATION_ERRORURL che non è https, privata o interna; evento sconosciuto; niente da cambiare.
404 NOT_FOUNDIl webhook non esiste in questo agente.
409 LIMIT_REACHEDL'agente ha già 10 webhook.
429 RATE_LIMITEDPiù di 20 prove al minuto.