QuantumOutbound kan eventdata naar je server sturen zodra er iets gebeurt — een connectieverzoek wordt verstuurd, een prospect accepteert, een bericht wordt verzonden of ontvangen, of een gesprek wordt getagd. In plaats van de API steeds te bevragen, ontvangt je endpoint een POST-verzoek met de volledige context.
Deze handleiding laat je zien hoe je een webhook-endpoint instelt, de events kiest die je belangrijk vindt en de payload verwerkt.
Vereisten
- Een QuantumOutbound-account met minimaal één actieve afzender
- Een publiek toegankelijk HTTPS-endpoint dat POST-verzoeken kan ontvangen
Hoe webhooks werken
QuantumOutbound activeert een webhook wanneer er een relevant event plaatsvindt in een gespreksthread in je inbox — of het nu wordt getriggerd door een campagneactie of een handmatige wijziging die je in de interface maakt. Elk event stuurt een HTTP POST-verzoek naar de URL die je hebt ingesteld.
Beschikbare event-typen
| Event-type | Wordt geactiveerd wanneer… |
|---|---|
activity.invitation.sent.v1 | Een connectieverzoek wordt verstuurd naar een prospect |
activity.connection.accepted.v1 | Een prospect je connectieverzoek accepteert |
activity.message.sent.v1 | Een bericht wordt verstuurd naar een prospect (inclusief geautomatiseerde campagneberichten en follow-ups) |
activity.message.received.v1 | Een prospect reageert op je gesprek |
activity.threadbox.tags.update.v1 | Een tag wordt toegevoegd aan of verwijderd van een gespreksthread |
Je webhook-endpoint instellen
- Klik in de linkerzijbalk onderaan op het Instellingen-tandwielpictogram.
- Klik op Webhooks.
- Plak je HTTPS-endpoint-URL.
- Kies de event-typen die je wilt ontvangen.
- Selecteer van welke agents je events wilt ontvangen.
- Klik op Opslaan.
💡 Tip: Gebruik de Test-knop om een voorbeeld-payload naar je endpoint te sturen. Zo bevestig je dat je server verzoeken kan ontvangen voordat er echte events worden geactiveerd.
De payload begrijpen
Elke webhook-aflevering 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 aflever-ID (gebruikt als idempotentiesleutel) | df313559-7cb1-... |
type | Het event-type | activity.connection.accepted.v1 |
timestamp | Wanneer het event plaatsvond (ISO 8601) | 2026-02-06T05:05:36+01:00 |
Het data-object bevat deze secties:
| Sectie | Wat het bevat |
|---|---|
data.agent | Naam van je agent, bedrijfsgegevens, diensten, merkstem en verkoopplaybook |
data.campaign | Campagne-ID, naam, status, doel, productpagina-URL, landingspagina-URL en campagnetype |
data.campaignContact | Contactstatus in de campagne (bijv. invitation_send), details van de laatste activiteit en beëindigingsindicator |
data.threadBox | Volledige namen van afzender en contact, tag-array, gespreksstatus, fit-score, AI-redenering, personanaam en antwoordstatus |
data.sender | Volledig LinkedIn-profiel van het afzenderaccount, kennisbankcontactgegevens en MBTI-persoonlijkheidsanalyse |
data.contact | LinkedIn-profiel van de prospect, kop, samenvatting, locatie, vaardigheden, huidige bedrijven en MBTI-analyse |
data.messages | Array van berichten in de gespreksthread |
Beveiligingsheaders bij elke aflevering:
| Header | Beschrijving |
|---|---|
webhook-signature | HMAC-handtekening om te verifiëren dat het verzoek van QuantumOutbound komt |
webhook-timestamp | Unix-tijdstempel van wanneer de payload is verstuurd |
webhook-idempotency-key | Unieke sleutel om dubbele verwerking te voorkomen |
webhook-key-id | Identificeert welke ondertekeningssleutel is gebruikt |
💡 Tip: De volledige payload is groot en bevat de complete agentcontext. Stuur eerst een test-webhook naar je endpoint en gebruik die JSON om alleen de velden te mappen die je nodig hebt in je handler.
Afleveringsgeschiedenis bekijken
Je kunt controleren of een webhook is geactiveerd en de afleveringsstatus bekijken direct in de app. Ga naar Instellingen → Webhooks om recente afleveringen, hun statuscodes en tijdstempels te zien.
Veelvoorkomende fouten
"De test werkt maar echte events worden niet geactiveerd"
Zorg ervoor dat je een actieve campagne hebt met prospects die door de workflow bewegen. Webhooks worden geactiveerd wanneer het systeem een actie uitvoert (uitnodiging verstuurt, bericht verstuurt, antwoord ontvangt, thread tagt) of wanneer je handmatig een tag wijzigt. Als er geen activiteit is, zijn er geen events om te versturen.
"Ik ontvang events maar er ontbreken velden in de payload"
De payload verschilt licht per event-type. Een activity.invitation.sent.v1-event bevat bijvoorbeeld geen antwoordgerelateerde velden. Controleer de test-payload voor je specifieke event-type om te zien welke velden zijn opgenomen.
"De payload is erg groot"
Dat is normaal. Elke aflevering bevat de volledige agentcontext (diensten, verkoopplaybook, merkstem) zodat je handler alles heeft wat nodig is om het event te routeren en verwerken. Parse alleen de velden die je nodig hebt.
Belangrijkste punten
- Webhooks sturen realtimedata naar je server wanneer events plaatsvinden — zowel geautomatiseerde campagneacties als handmatige wijzigingen.
- Vijf event-typen dekken de volledige outreach-levenscyclus: uitnodiging verstuurd, connectie geaccepteerd, bericht verstuurd, bericht ontvangen en tag bijgewerkt.
- De payload bevat de volledige agent-, campagne- en contactcontext in een geneste JSON-structuur.
- Beveiligingsheaders stellen je in staat te verifiëren dat elke aflevering van QuantumOutbound afkomstig is.
- Begin met een test-webhook om de volledige payloadstructuur vast te leggen voordat je je handler bouwt.