Naar de hoofdinhoud

Webhooks

Een webhook is een verzoek dat de telefoon naar een adres naar keuze stuurt, telkens wanneer er iets met een gesprek gebeurt. Zo kan een CRM de klantkaart openen vóór de tweede beltoon, een gesprek vastleggen als het eindigt, of een lampje op een wandbord laten branden. Een webhook vraagt geen inkomende firewallregels: de telefoon belt u. Omdat de verzoeken vanaf de werkplek worden verstuurd, hoeft het adres alleen vanaf die computer bereikbaar te zijn — een intern http://crm.local/calls werkt net zo goed als een openbaar HTTPS-adres.

Webhooks staan na de installatie uit, tot u ze aanzet. Ze werken naast de lokale REST-API: een gebeurtenis zegt dat er iets veranderd is, de API geeft de actuele gegevens.

Ze aanzetten​

Open Instellingen → Integratie. Webhooks is het eerste onderdeel van het tabblad.

  1. Vink Een ander systeem over gesprekken vertellen aan. Er wordt één verzoek verzonden voor elke gebeurtenis die u hieronder aanvinkt.
  2. Vul het Adres in dat de gebeurtenissen moet ontvangen, bijvoorbeeld https://crm.local/calls.
  3. Kies de Methode: POST (de standaard) of GET.
  4. Vink onder Gebeurtenissen aan wat er verstuurd moet worden: Een nieuw gesprek, Een gesprek dat eindigt, Een gesprek dat van toestand verandert.
  5. Stel eventueel onder Autorisatie een koptekst in die uw ontvanger kan controleren: een Koptekstnaam (Authorization wordt voorgesteld) en een Koptekstwaarde. De waarde wordt bewaard in de sleutelhanger van de computer, nooit in een instellingenbestand; na het opslaan toont het veld Opgeslagen — typ om hem te vervangen.
  6. Druk op Een testgebeurtenis verzenden om te zien of ze aankomt. Er wordt één gebeurtenis verstuurd voor een gesprek dat nooit heeft plaatsgevonden, met dezelfde kopteksten als een echte. Leg het ruwe verzoek vast en bouw uw ontvanger op wat uw versie werkelijk verstuurt.

Het deel van het programma dat de verzoeken verstuurt, is de module Integratie; die kan worden uitgezet bij Modules.

De gebeurtenissen​

Aangevinkt alsGebeurtenisVerstuurd wanneer
Een nieuw gesprekcall-startedEen inkomend gesprek begint over te gaan of er wordt een uitgaand gesprek gestart.
Een gesprek dat van toestand verandertcall-state-changedDe state van het gesprek verandert: het wordt aangenomen, door een van beide kanten in de wacht gezet of hervat, of het gaat een vergadering in of uit. Dempen verstuurt haar niet.
Een gesprek dat eindigtcall-endedHet gesprek is beëindigd.

Elke gebeurtenis kan los worden aangevinkt. Een pop-up met de klantkaart heeft alleen de eerste nodig; een gespreksregistratie alleen de laatste. call-started wordt als eerste verstuurd en moet snel worden afgehandeld.

Hoe het verzoek eruitziet​

Met het adres https://crm.local/calls en de methode POST stuurt de telefoon dit. De body is JSON, en de koptekst is degene die u onder Autorisatie hebt ingesteld:

POST /calls HTTP/1.1
Host: crm.local
Authorization: Bearer my-secret-token
Content-Type: application/json
User-Agent: ai-softphone/1.1.5-macos-dmg

De User-Agent bevat de versie van het programma en de manier waarop het is geïnstalleerd.

Een inkomend gesprek, gebeurtenis voor gebeurtenis​

Een gesprek van toestel 1020 naar account 1002 gaat over, wordt aangenomen, en wie het aannam hangt vier seconden later op. Met alle drie de gebeurtenissen aangevinkt krijgt de ontvanger drie verzoeken, na elkaar. Ze dragen allemaal dezelfde id en seance_id.

1. Het gaat over: call-started​

{
"account": "1002@pbx.example.com",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90",
"answered_by": "no",
"callstart_ts": "1791021263333",
"callstate_ts": "1791021263333",
"dialed": "",
"direction": "in",
"duration_s": "0",
"event": "call-started",
"event_ts": "1791021263333",
"id": "5b1c0a6e-0c7e-4c53-9f57-2c4f1f0d6a11",
"name": "Jack Russel",
"number": "1020",
"reason": "none",
"seance_id": "e3f0b9f4-1a2c-4d8b-9c35-6a7b8c9d0e1f",
"state": "ringing-in",
"uri": "sip:1020@pbx.example.com"
}

Dit is het moment om de beller op te zoeken via number en de klantkaart te tonen. state is ringing-in en duration_s is 0.

2. Het wordt aangenomen: call-state-changed​

Ongeveer drie seconden later:

{
"account": "1002@pbx.example.com",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90",
"answered_by": "no",
"callstart_ts": "1791021263333",
"callstate_ts": "1791021266126",
"dialed": "",
"direction": "in",
"duration_s": "0",
"event": "call-state-changed",
"event_ts": "1791021266131",
"id": "5b1c0a6e-0c7e-4c53-9f57-2c4f1f0d6a11",
"name": "Jack Russel",
"number": "1020",
"reason": "none",
"seance_id": "e3f0b9f4-1a2c-4d8b-9c35-6a7b8c9d0e1f",
"state": "active",
"uri": "sip:1020@pbx.example.com"
}

state is nu active, en callstate_ts is opgeschoven naar het moment van de verandering, terwijl callstart_ts blijft waar het was.

3. Het eindigt: call-ended​

Vier seconden gesprek later:

{
"account": "1002@pbx.example.com",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90",
"answered_by": "no",
"callstart_ts": "1791021263333",
"callstate_ts": "1791021270400",
"dialed": "",
"direction": "in",
"duration_s": "4",
"event": "call-ended",
"event_ts": "1791021270406",
"id": "5b1c0a6e-0c7e-4c53-9f57-2c4f1f0d6a11",
"name": "Jack Russel",
"number": "1020",
"reason": "local-hangup",
"seance_id": "e3f0b9f4-1a2c-4d8b-9c35-6a7b8c9d0e1f",
"state": "ended",
"uri": "sip:1020@pbx.example.com"
}

state is ended, duration_s is de duur van het gesprek, en reason zegt wie het beëindigde: hier local-hangup, omdat de persoon aan deze telefoon ophing.

Een uitgaand gesprek, gebeurtenis voor gebeurtenis​

Hetzelfde toestel wordt gebeld vanaf account 1002: de persoon kiest 1020, de telefoon gaat over, de andere kant neemt op, praat zeven seconden en hangt op. De ontvanger krijgt vier verzoeken, één meer dan bij een inkomend gesprek, omdat een uitgaand gesprek een eigen toestand heeft terwijl het aan de andere kant overgaat.

1. Het wordt gekozen: call-started​

{
"account": "1002@pbx.example.com",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90",
"answered_by": "no",
"callstart_ts": "1791023883072",
"callstate_ts": "1791023883072",
"dialed": "1020",
"direction": "out",
"duration_s": "0",
"event": "call-started",
"event_ts": "1791023883072",
"id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24",
"name": "",
"number": "1020",
"reason": "none",
"seance_id": "c47d2e90-6b13-4f85-a2d7-18e9b0f35a6c",
"state": "dialing",
"uri": "sip:1020@pbx.example.com:5060"
}

direction is out, state is dialing, en dialed bevat het nummer zoals het werd gekozen. De telefoon kent de naam van de andere partij nog niet, dus name is leeg.

2. Het gaat over aan de andere kant: call-state-changed​

Een halve seconde later:

{
"account": "1002@pbx.example.com",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90",
"answered_by": "no",
"callstart_ts": "1791023883072",
"callstate_ts": "1791023883591",
"dialed": "1020",
"direction": "out",
"duration_s": "0",
"event": "call-state-changed",
"event_ts": "1791023883591",
"id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24",
"name": "",
"number": "1020",
"reason": "none",
"seance_id": "c47d2e90-6b13-4f85-a2d7-18e9b0f35a6c",
"state": "ringing-out",
"uri": "sip:1020@pbx.example.com:5060"
}

state is ringing-out.

3. De andere kant neemt op: call-state-changed​

Vier seconden daarna:

{
"account": "1002@pbx.example.com",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90",
"answered_by": "no",
"callstart_ts": "1791023883072",
"callstate_ts": "1791023887072",
"dialed": "1020",
"direction": "out",
"duration_s": "0",
"event": "call-state-changed",
"event_ts": "1791023887076",
"id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24",
"name": "Jack Russel",
"number": "1020",
"reason": "none",
"seance_id": "c47d2e90-6b13-4f85-a2d7-18e9b0f35a6c",
"state": "active",
"uri": "sip:1020@pbx.example.com"
}

state is active. De name is nu ingevuld, en de uri is het adres van de partij zoals het antwoord het meldde. duration_s is nog 0: dat telt vanaf dit moment.

4. Het eindigt: call-ended​

Zeven seconden later hangt de andere kant op:

{
"account": "1002@pbx.example.com",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90",
"answered_by": "no",
"callstart_ts": "1791023883072",
"callstate_ts": "1791023894781",
"dialed": "1020",
"direction": "out",
"duration_s": "7",
"event": "call-ended",
"event_ts": "1791023894789",
"id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24",
"name": "Jack Russel",
"number": "1020",
"reason": "remote-hangup",
"seance_id": "c47d2e90-6b13-4f85-a2d7-18e9b0f35a6c",
"state": "ended",
"uri": "sip:1020@pbx.example.com"
}

duration_s is 7, en reason is remote-hangup, omdat de andere kant het gesprek beëindigde. Als u zelf ophangt, is het local-hangup, zoals bij het inkomende gesprek hierboven.

De toestanden naast elkaar​

Inkomend gesprekUitgaand gesprek
call-startedringing-indialing
call-state-changedactiveringing-out, dan active
call-endedendedended

De velden​

Elke waarde is een string, ook getallen en tijdstempels: "duration_s": "42". Een onbekend moment is een lege string. De namen volgen één conventie: _id is een identificatie, _ts is Unix-tijd in milliseconden (UTC), _s is een duur in seconden — net als in de REST-API, waar de waarden JSON-getallen zijn.

VeldBetekenis
eventcall-started, call-state-changed of call-ended.
idHet gesprek: dezelfde UUID als in GET /calls en /calls/{id}/…, en dezelfde in elke gebeurtenis van het gesprek.
seance_idHet gesprek in bredere zin waartoe dit gesprek behoort; zie hieronder.
directionin of out.
stateDezelfde waarden als in GET /calls: dialing, ringing-out, ringing-in, active, hold (in de wacht gezet door deze telefoon), onhold (in de wacht gezet door de andere partij), conference of ended.
numberHet nummer van de andere partij. Koppel uw CRM-gegevens op dit veld.
nameDe naam van de andere partij, uit Contacten; kan leeg zijn, en later in het gesprek worden ingevuld, zoals bij het uitgaande gesprek hierboven.
uriHet SIP-adres van de andere partij.
dialedDe gekozen cijfers, bij een uitgaand gesprek; leeg bij een inkomend gesprek.
account, account_idDe lijn waarop het gesprek loopt: username@server, en de identificatie uit GET /accounts.
event_tsWanneer de gebeurtenis plaatsvond.
callstart_tsWanneer de telefoon voor het eerst van het gesprek wist.
callstate_tsWanneer het gesprek zijn huidige state binnenging.
duration_sGesprekstijd in seconden, van opnemen tot ophangen. Ingevuld bij call-ended voor een aangenomen gesprek; anders 0.
reasonHoe het gesprek eindigde: local-hangup, remote-hangup, busy, no-answer, cancelled…; tot dan none.
answered_byno als een persoon opnam; anders wat het gesprek aannam.

Eén gesprek over doorverbindingen heen​

seance_id groepeert de gesprekken die samen één gesprek vormen. Een gesprek dat vanaf nul wordt gevoerd of ontvangen, begint een nieuwe. Een gesprek dat door doorverbinden ontstaat, een gesprek dat een ander vervangt, een ruggespraak over een gesprek en elk gesprek dat in een vergadering wordt samengevoegd, houden de seance_id van het gesprek waaruit ze voortkwamen.

Tussen telefoons reist het mee in de SIP-koptekst X-Seance-Id: als een gesprek wordt doorverbonden naar een collega die ook AI Softphone gebruikt, en de centrale de koptekst doorgeeft, melden beide werkplekken dezelfde seance_id.

GET in plaats van POST​

GET is voor ontvangers die geen body kunnen aannemen, zoals een ouder CRM of een scriptbrug. Dezelfde velden worden dan als queryparameters verstuurd.

Met GET kan het adres een sjabloon zijn: elk [veld] wordt vervangen door de waarde van dat veld, procentgecodeerd. Bijvoorbeeld:

https://crm.local/pop?phone=[number]&call=[id]

De plaatshouders gebruiken de veldnamen hierboven. Sjablonen die met de eerdere namen zijn opgeslagen ([accountId], [at], [duration], [answeredBy], [seanceId]) blijven werken.

Hoe de gebeurtenissen worden bezorgd​

GedragWat het voor u betekent
Gebeurtenissen gaan in een wachtrij en worden niet vanuit het gesprek zelf verstuurdEen trage ontvanger vertraagt nooit het overgaan, gesprekken of doorverbindingen.
Een volle wachtrij laat gebeurtenissen vallenAls uw ontvanger niet meer antwoordt, gaan gebeurtenissen verloren maar blijft de telefoon werken. Houd webhooks_dropped_total in de gaten.
Geweigerde en onbereikbare bezorgingen worden geteldEen stijgende webhooks_failed_total terwijl webhooks_delivered_total stilstaat, wijst naar de ontvanger.
Gebeurtenissen komen op volgorde aanGesprek begonnen, dan de toestandswijzigingen, dan gesprek beëindigd. Gebruik callstate_ts om opgeslagen gebeurtenissen te ordenen, niet het tijdstip waarop ze binnenkwamen.
Minstens één keerDezelfde gebeurtenis kan twee keer komen. id, event en callstate_ts samen identificeren een gebeurtenis: laat uw verwerking er een overslaan die ze al heeft gezien.

De gebeurtenissen ontvangen​

De enige regel voor een ontvanger: antwoord meteen 200, en doe het werk daarna. Een trage ontvanger vertraagt de telefoon niet, maar vult de wachtrij, en een volle wachtrij laat gebeurtenissen vallen.

Bijvoorbeeld in Node.js met Express:

const express = require("express");
const app = express();
app.use(express.json());

const SECRET = process.env.SOFTPHONE_SECRET; // the Header value from Settings

app.all("/calls", (req, res) => {
if (req.get("Authorization") !== SECRET) return res.sendStatus(401);

// POST sends a JSON body, GET sends query parameters
const call = Object.keys(req.body || {}).length ? req.body : req.query;
res.sendStatus(200); // answer first

setImmediate(() => { // then do the work
if (call.event === "call-started" && call.direction === "in") {
openCustomerCard(call.number, call.name); // your code
}
if (call.event === "call-ended") {
logCall(call.id, Number(call.duration_s), call.reason); // your code
}
});
});

app.listen(8080);

Om de afloop van een gesprek vast te leggen — aangenomen, gemist, geweigerd — neemt u het item met dezelfde seance_id en number uit GET /history?limit=20 van de REST-API. Als uw dienst na een pauze weer start, leest u GET /history?limit=200 en slaat u op wat u hebt gemist: webhooks voor de realtime, de geschiedenis om de gaten te vullen.

Om de verzoeken te zien voordat het CRM klaar is, richt u het Adres op een online verzoekinspecteur en drukt u op Een testgebeurtenis verzenden.

Als er niets aankomt​

SymptoomWat u controleert
Helemaal geen webhooksDruk op Een testgebeurtenis verzenden. Komt die aan, dan zijn de gebeurtenissen die u nodig hebt niet aangevinkt; zo niet, dan is het adres fout of vanaf de werkplek niet bereikbaar.
webhooks_failed_total blijft stijgenDe ontvanger weigert de verzoeken of is onbereikbaar. Bekijk zijn logboek, en of hij antwoordt op een eenvoudig verzoek vanaf de werkplek.
webhooks_dropped_total is groter dan nulDe ontvanger was te lang te traag en de wachtrij liep vol. Antwoord eerst 200 en verwerk daarna.
Dezelfde gebeurtenis twee keerTe verwachten bij bezorging van minstens één keer. Behandel gebeurtenissen met dezelfde id, event en callstate_ts als één.