Webhooks gebruiken

SalesMind AI kan gebeurtenisgegevens naar je server sturen op het moment dat er iets gebeurt — een connectieverzoek gaat uit, een prospect accepteert, een bericht wordt verzonden of ontvangen, of een gesprek krijgt een tag. In plaats van de API te pollen, krijgt je endpoint een POST-verzoek met de volledige context.

Deze gids laat zien hoe je een webhook-endpoint instelt, de events kiest die je belangrijk vindt en de payload verwerkt.

Vereisten

• Een SalesMind AI-account met minstens één actieve sender
• Een openbaar bereikbaar HTTPS-endpoint dat POST-verzoeken kan ontvangen

Hoe webhooks werken

SalesMind AI vuurt een webhook af telkens als er een relevant event plaatsvindt op een gespreksthread in je inbox — of het nu door een campagneactie of een handmatige wijziging in de interface wordt veroorzaakt. Elk event stuurt een HTTP-POST-verzoek naar de URL die je hebt ingesteld.

Beschikbare eventtypen

Eventtype	Vuurt af wanneer…
activity.invitation.sent.v1	Een connectieverzoek naar een prospect wordt gestuurd
activity.connection.accepted.v1	Een prospect je connectieverzoek accepteert
activity.message.sent.v1	Een bericht naar een prospect wordt gestuurd (inclusief automatische campagneberichten en follow-ups)
activity.message.received.v1	Een prospect op je gesprek antwoordt
activity.threadbox.tags.update.v1	Een tag op een gespreksthread wordt toegevoegd of verwijderd

Deze vijf activity.*-events zijn wat een normaal account kan abonneren en ontvangen. Er bestaat een zesde event, user.register.v1, maar dat is alleen voor beheerders — normale accounts ontvangen het nooit en het wordt automatisch verwijderd als je je erop probeert te abonneren. webhook.test.v1 is een eenmalig event dat via de knop Test wordt verstuurd, geen event waarop je je abonneert.

Je webhook-endpoint instellen

1. Klik in de linker zijbalk onderaan op het tandwiel Instellingen.
2. Klik op Webhooks.
3. Plak de URL van je HTTPS-endpoint.
4. Kies de eventtypen die je wilt ontvangen.
5. Selecteer van welke agenten je events wilt ontvangen.
6. Klik op Opslaan.

💡 Tip: Gebruik de knop Test om een voorbeeld-payload naar je endpoint te sturen. Zo bevestig je dat je server verzoeken kan ontvangen voordat er echte events afgaan.

Endpoints beheren met de API

Je kunt webhook-endpoints via de API beheren in plaats van via de interface. Elk endpoint heeft je X-API-KEY-header nodig en staat onder https://api.sales-mind.ai//v1/webhooks.

Methode	Endpoint	Doel
POST	/v1/webhooks/endpoints	Een nieuw endpoint registreren
GET	/v1/webhooks/endpoints	Je endpoints opsommen
GET	/v1/webhooks/endpoints/{id}	Eén endpoint ophalen
DELETE	/v1/webhooks/endpoints/{id}	Een endpoint verwijderen
GET	/v1/webhooks/endpoints/{id}/rotate-secret	Een nieuw ondertekeningsgeheim ophalen
PUT	/v1/webhooks/endpoints/{id}/suspend	Een endpoint pauzeren of hervatten
GET	/v1/webhooks/events	De events opsommen waarop je je kunt abonneren
PUT	/v1/webhooks/endpoints/{id}/events	De geabonneerde events wijzigen
GET	/v1/webhooks/endpoints/{id}/test	Een testlevering sturen

⚠️ De registratie geeft je ondertekeningsgeheim niet terug. Nadat je een endpoint hebt geregistreerd, roep je rotate-secret aan om het geheim op te halen waarmee je leveringen verifieert.

Je endpoint moet een openbare HTTPS-URL zijn. SalesMind AI controleert dit bij het afleveren van een event, niet bij de registratie — een niet-HTTPS- of privé-URL wordt dus eerst geaccepteerd en faalt daarna bij de levering.

De payload begrijpen

Elke webhooklevering stuurt een JSON-object met drie velden op het hoogste niveau en een genest data-object met de volledige context.

Velden op het hoogste niveau:

Veld	Beschrijving	Voorbeeld
id	Unieke leverings-ID (gebruikt als idempotentiesleutel)	df313559-7cb1-...
type	Het eventtype	activity.connection.accepted.v1
timestamp	Wanneer het event plaatsvond (ISO 8601)	2026-02-06T05:05:36+01:00

Het data-object bevat deze onderdelen:

Onderdeel	Wat het bevat
data.agent	Je agentnaam, bedrijfsgegevens, diensten, merktoon en sales-playbook
data.campaign	Campagne-ID, naam, status, doel, product-pagina-URL, landingspagina-URL en campagnetype
data.campaignContact	Contactstatus in de campagne (bijv. invitation_send), details van de laatste activiteit en beëindigd-vlag
data.threadBox	Volledige namen van sender en contact, tags-array, gespreksstatus, fit score, AI-onderbouwing, personanaam en antwoordstatus
data.sender	Volledig LinkedIn-profiel van het verzendende account, contactgegevens uit de kennisbank en MBTI-persoonlijkheidsanalyse
data.contact	LinkedIn-profiel van de prospect, headline, samenvatting, locatie, vaardigheden, huidige bedrijven en MBTI-analyse
data.messages	Array met berichten in de gespreksthread

💡 Tip: De volledige payload is groot en bevat de complete agentcontext. Stuur eerst een test-webhook naar je endpoint en gebruik die JSON dan om in je handler alleen de velden te mappen die je nodig hebt.

De handtekening verifiëren

Elke levering draagt vier headers waarmee je kunt bevestigen dat hij echt van SalesMind AI kwam:

Header	Waarde
Webhook-Signature	Base64-gecodeerde HMAC-SHA256 van de ondertekende tekenreeks
Webhook-Timestamp	Unix-epoch-seconden, gebruikt in de ondertekende tekenreeks
Webhook-Idempotency-Key	{eventId}:{endpointId} — gebruik hem om dubbele leveringen te negeren
Webhook-Key-Id	current — welk ondertekeningsgeheim is gebruikt

De ondertekende tekenreeks is:

{Webhook-Timestamp}.{endpointId}.{sha256_hex(rawBody)}

Onderteken de waarde uit de Webhook-Timestamp-header, niet het ISO-veld timestamp in de body — die zijn verschillend.

Een levering verifiëren:

1. Lees de ruwe request-body, de Webhook-Timestamp-header en de Webhook-Signature-header.
2. Bereken de SHA-256-hex-digest van de ruwe body en bouw dan {Webhook-Timestamp}.{endpointId}.{sha256_hex}.
3. Bereken Base64(HMAC-SHA256(die tekenreeks, jouw endpoint-geheim)) en vergelijk het met Webhook-Signature via een constante-tijdvergelijking.
4. Optioneel: weiger de levering als Webhook-Timestamp ouder is dan een venster dat je zelf kiest (bijvoorbeeld 5 minuten).

💡 Het replay-venster van 5 minuten is een controle die je aan jouw kant toevoegt. SalesMind AI dwingt het niet af.

⚠️ Werk na het roteren van je geheim je opgeslagen geheim meteen bij. SalesMind AI ondertekent altijd met het huidige geheim, dus leveringen schakelen meteen over op het nieuwe geheim — er is geen overgangsperiode aan de ondertekeningskant.

Leveringsgeschiedenis bekijken

Je kunt direct in de app controleren of een webhook is afgegaan en de leveringsstatus bekijken. Ga naar Instellingen → Webhooks om recente leveringen, hun statuscodes en tijdstempels te zien.

Je kunt leveringen ook via de API ophalen:

Methode	Endpoint	Doel
GET	/v1/webhooks/deliveries	Leveringen opsommen (filter op endpointId, status, type)
GET	/v1/webhooks/deliveries/{id}	Eén levering ophalen, inclusief de payload
POST	/v1/webhooks/deliveries/{id}/replay	Een levering opnieuw sturen als nieuw event

Elke levering heeft een status: pending, delivered, failed of suspended.

Hoe leveringspogingen werken:

• Elke poging heeft een time-out na 5 seconden.
• Een 2xx-antwoord markeert de levering als delivered en zet de foutteller van het endpoint terug.
• Elk ander antwoord — of een time-out — markeert hem als failed en probeert opnieuw met een backoff van 5, 10, 20, 60 en dan 300 seconden (tot 5 herhalingen, dus 6 pogingen in totaal).
• Na 10 opeenvolgende fouten pauzeert SalesMind AI het endpoint automatisch. Nieuwe events voor een gepauzeerd endpoint worden als suspended geregistreerd en overgeslagen tot je het hervat.

Veelvoorkomende valkuilen

"De test werkt maar echte events gaan niet af"

Zorg dat je een actieve campagne hebt met prospects die door de workflow bewegen. Webhooks gaan af wanneer het systeem een actie uitvoert (een uitnodiging stuurt, een bericht stuurt, een antwoord krijgt, een thread tagt) of wanneer je handmatig een tag wijzigt. Als er geen activiteit is, zijn er geen events om te sturen.

"Ik krijg events maar er ontbreken velden in de payload"

De payload verschilt licht per eventtype. Een activity.invitation.sent.v1-event heeft bijvoorbeeld geen antwoordgerelateerde velden. Bekijk de test-payload voor jouw specifieke eventtype om te zien welke velden zijn opgenomen.

"De payload is erg groot"

Dat is normaal. Elke levering bevat de volledige agentcontext (diensten, sales-playbook, merktoon) zodat je handler alles heeft om het event te routeren en te verwerken. Parse alleen de velden die je nodig hebt.

"Mijn endpoint-URL werd geaccepteerd maar ontvangt nooit iets"

Je endpoint moet een openbare HTTPS-URL zijn. SalesMind AI controleert dit bij het afleveren van een event, niet bij de registratie — een niet-HTTPS- of privé-URL wordt dus eerst geaccepteerd en faalt daarna bij de levering. Bekijk je leveringsgeschiedenis op mislukte pogingen.

Belangrijkste punten

• Webhooks sturen realtime gegevens naar je server wanneer events plaatsvinden — zowel automatische campagneacties als handmatige wijzigingen.
• Een normaal account abonneert zich op de vijf activity.*-events; user.register.v1 is alleen voor beheerders en webhook.test.v1 is enkel het testevent.
• Beheer endpoints, events en leveringen via de API onder https://api.sales-mind.ai//v1/webhooks — authenticeer met X-API-KEY.
• Verifieer elke levering met de headers Webhook-Signature en Webhook-Timestamp; het ondertekeningsgeheim komt uit rotate-secret, niet uit de registratie.
• Leveringen worden met backoff opnieuw geprobeerd en een endpoint wordt na 10 opeenvolgende fouten gepauzeerd — bekijk en herhaal via de leveringsgeschiedenis.

FAQ

Welke events kan mijn account ontvangen? Normale accounts ontvangen de vijf activity.*-events. user.register.v1 is alleen voor beheerders en webhook.test.v1 is enkel het testevent.

Hoe verifieer ik dat een webhook van SalesMind AI kwam? Herbereken de handtekening uit de ruwe body en de Webhook-Timestamp-header en vergelijk hem met de Webhook-Signature-header. Zie "De handtekening verifiëren" hierboven.

Hoe krijg ik mijn ondertekeningsgeheim? De registratie geeft het niet terug. Roep het rotate-secret-endpoint aan om een nieuw geheim te krijgen en werk je opgeslagen kopie meteen bij.

Waarom werd mijn endpoint gepauzeerd? SalesMind AI pauzeert een endpoint na te veel mislukte leveringen op rij — standaard 10. Herstel je server en hervat het endpoint dan.

Kan ik een gemiste webhook opnieuw sturen? Ja. Gebruik het replay-endpoint om een eerdere levering opnieuw als nieuw event te sturen.

Mijn URL werd geaccepteerd maar er komen geen events aan. Waarom? De HTTPS- en openbare-URL-controle draait op het moment van levering, niet bij de registratie. Een foute URL wordt eerst geaccepteerd en faalt daarna bij de levering. Bekijk je leveringsgeschiedenis.