API version 1 · updated 25 October 2026
With the API and webhooks, the calls BelBuddy answers flow automatically into your own software: CRM, ticketing system or scheduling. Customers create keys and webhooks themselves on a computer: log in at app.belbuddy.eu and choose Settings › Integrations with your software. The API is included in the Team plan; webhooks are available on Business (€ 19 per month extra) and Team.
Send the key in the Authorization header. A key belongs to one business and gives read-only access to that business's calls.
curl https://app.belbuddy.eu/api/v1/gesprekken \ -H "Authorization: Bearer bb_live_..."
A maximum of 600 requests per minute per key. A revoked key stops working immediately.
| Request | What you get |
|---|---|
GET /api/v1/bedrijf | Name, number and opening hours |
GET /api/v1/gesprekken | The most recent calls (without transcript). Filters: sinds (Unix time), uitkomst (afspraak, terugbellen, beantwoord), limiet (1–200) |
GET /api/v1/gesprekken/{id} | A single call, with the full transcript |
{
"id": "conv_...",
"gestart": "2026-10-25T10:42:00+02:00",
"duur_seconden": 74,
"beller": "+31611223344",
"uitkomst": "terugbellen",
"titel": "Graag terugbellen: Ali Yilmaz",
"notitie": {
"naam": "Ali Yilmaz", "telefoon": "06 11 22 33 44",
"wilde": "Afspraak van donderdag verzetten",
"samenvatting": "...",
"afspraak": null,
"terugbellen": {"naam": "Ali Yilmaz", "telefoon": "06 11 22 33 44", "onderwerp": "afspraak verzetten"}
},
"transcript": [{"wie": "BelBuddy", "sec": 0, "tekst": "..."}, {"wie": "Beller", "sec": 3, "tekst": "..."}]
}
After every completed call, BelBuddy sends a POST to your address (https only) within a few seconds, with the event gesprek.afgerond. The call is in data.gesprek, in the same format as above.
POST https://uw-systeem.nl/belbuddy
BelBuddy-Event: gesprek.afgerond
BelBuddy-Signature: t=1792900000,v1=5f2b...
{"id": "evt_...", "type": "gesprek.afgerond", "gemaakt": "...", "klant": "...", "data": {"gesprek": {...}}}
Verify the signature. Compute an HMAC-SHA256 using the webhook secret (starts with whsec_) over t + "." + the raw body, and compare it with v1. Reject messages where t is more than five minutes old.
# Python
import hmac, hashlib, time
def echt(geheim, kop, body):
d = dict(p.split("=", 1) for p in kop.split(","))
if abs(time.time() - int(d["t"])) > 300:
return False
verwacht = hmac.new(geheim.encode(), f"{d['t']}.".encode() + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(verwacht, d["v1"])
Respond with a 2xx status. If delivery fails, we retry after 1 minute, 10 minutes and 1 hour. The delivery log is in the app. The Test button sends a sample message with type test.
Email [email protected].