Meer conversies Betere prestaties Direct aan de slag

Zo stel je webhooks in

Met webhooks stuur je gespreksgegevens automatisch naar je eigen systemen, zoals een CRM of datawarehouse. Bij elk gesprek sturen we een bericht naar een adres (endpoint) dat jij opgeeft. Dit artikel is vooral bedoeld voor de developer die de koppeling bouwt.

Let op: je hebt beheerdersrechten nodig in de Qooqie call tracking applicatie.

Webhooks instellen

  1. Ga binnen de Qooqie call tracking applicatie naar Integraties > Webhooks.
  2. Bij ‘API versie’ is alleen versie 1.0 beschikbaar.
  3. Zet ‘Vraag payload keys in camelCase aan’ aan als je veldnamen wilt als fromNumber in plaats van from_number. Alleen de veldnamen op het hoogste niveau veranderen.
  4. Open het event waarvoor je een webhook wilt ontvangen (zie hieronder).
  5. Vul bij ‘URL endpoint’ het adres in. Gebruik één https-adres per regel, maximaal tien. Gebruik een adres van een openbare website, dus geen intern adres, IP-adres of poort.
  6. Zet ‘Actief’ aan.
  7. Klik op ‘Opslaan’. Wijzigingen gelden voor nieuwe oproepen, meestal binnen een minuut.
De webhookpagina met een geopend event, het veld ‘URL endpoint’ en de schakelaar ‘Actief’.

Welke events zijn er?

  • ‘Basis leads’ – Na een beantwoord gesprek van een nieuwe beller zonder websitebezoek, bijvoorbeeld via een offline campagne.
  • ‘Leads met sessie’ – Na een beantwoord gesprek van een nieuwe beller die via je website belde.
  • ‘Terugkerende leads’ – Na een beantwoord gesprek van een beller die al eerder heeft gebeld.
  • ‘Gemiste leads’ – Als een oproep niet is opgenomen.
  • ‘Actieve leads met sessie’ – Direct bij het begin van een inkomende oproep, nog tijdens het gesprek.
  • ‘Leadgenerator API’ – Als via de Leadgenerator API een trackingnummer wordt aangemaakt, gewijzigd, verwijderd of hersteld.

Welke velden staan in het bericht?

We sturen het bericht als POST met JSON. Per event staan onder andere deze velden in het bericht:

  • Bij een gesprek: id, call_id, from_number, to_number, start, end, duration, duration_real, campaign_id, campaign_name, campaign_media_type, lead_class, lead_class_value, lead_type, branch_id, branch_name, lead_description, external_id en recording.
  • Bij ‘Leads met sessie’ komen daar de gegevens van het websitebezoek bij, zoals domain, pathname, referrer, keywords, gclid, cid, de UTM-tags (utm_source, utm_medium, utm_campaign, utm_term, utm_content), group_name en ad_name. Bij gemiste en terugkerende leads staan deze gegevens er ook in als de beller via je website kwam.
  • ‘Actieve leads met sessie’ bevat beller, nummer, campagne en het websitebezoek als dat bekend is. Duur en beoordeling staan er nog niet in.
  • ‘Leadgenerator API’ bevat phone_number, external_id en action.

Authenticatie

Open ‘API secret en Basic Auth’:

  • API secret – Vul een lange willekeurige tekst in zonder spaties en bewaar die ook in je eigen systeem. Elke webhook krijgt dan een X-Signature-header: een HMAC-SHA256 van de JSON met deze sleutel. Zo controleer je dat het bericht van Qooqie komt.
  • Basic Auth – Vraagt je endpoint om Basic Auth? Vul dan ‘Basic Auth gebruikersnaam’ en ‘Basic Auth wachtwoord’ in. We sturen dan bij elk verzoek een Authorization-header mee.

Na opslaan worden secret, wachtwoord en tokens in de URL niet meer getoond.

Herhaalpogingen en rate limits

  • Antwoord binnen 5 seconden met een 2xx-status.
  • Bij een time-out of serverfout proberen we het later opnieuw, een aantal keer, met steeds meer tijd ertussen.
  • Antwoordt je endpoint met een blijvende fout, zoals 400, 401, 403, 404 of 422? Dan proberen we het niet opnieuw.
  • Begrenst je endpoint het aantal verzoeken en stuurt het daarbij een X-RateLimit-Limit-header mee? Dan pauzeren we de webhooks van je organisatie tijdelijk. We wachten de tijd uit de Retry-After- of X-RateLimit-Reset-header af, of 60 seconden als die ontbreekt. Daarna proberen we het opnieuw.

Klaar voor meer inzicht, meer leads en betere conversies?

Begin met het optimaliseren van jouw resultaten.

Probeer een gratis proefperiode van 14 dagen, geen creditcard vereist.