QuantumOutbound kann Event-Daten an Ihren Server senden, sobald etwas passiert — eine Verbindungsanfrage wird gesendet, ein Prospect nimmt an, eine Nachricht wird gesendet oder empfangen, oder ein Gespräch wird getaggt. Anstatt die API regelmäßig abzufragen, erhält Ihr Endpoint eine POST-Anfrage mit dem vollständigen Kontext.
Diese Anleitung zeigt Ihnen, wie Sie einen Webhook-Endpoint einrichten, die gewünschten Events auswählen und den Payload verarbeiten.
Voraussetzungen
- Ein QuantumOutbound-Konto mit mindestens einem aktiven Absender
- Ein öffentlich zugänglicher HTTPS-Endpoint, der POST-Anfragen empfangen kann
Wie Webhooks funktionieren
QuantumOutbound löst einen Webhook aus, wenn ein relevantes Event in einem Gesprächsthread in Ihrem Posteingang stattfindet — sei es durch eine Kampagnenaktion oder eine manuelle Änderung in der Benutzeroberfläche. Jedes Event sendet eine HTTP-POST-Anfrage an die von Ihnen konfigurierte URL.
Verfügbare Event-Typen
| Event-Typ | Wird ausgelöst, wenn… |
|---|---|
activity.invitation.sent.v1 | Eine Verbindungsanfrage an einen Prospect gesendet wird |
activity.connection.accepted.v1 | Ein Prospect Ihre Verbindungsanfrage annimmt |
activity.message.sent.v1 | Eine Nachricht an einen Prospect gesendet wird (einschließlich automatisierter Kampagnennachrichten und Follow-ups) |
activity.message.received.v1 | Ein Prospect auf Ihr Gespräch antwortet |
activity.threadbox.tags.update.v1 | Ein Tag zu einem Gesprächsthread hinzugefügt oder entfernt wird |
Ihren Webhook-Endpoint einrichten
- Klicken Sie in der linken Seitenleiste unten auf das Einstellungen-Zahnradsymbol.
- Klicken Sie auf Webhooks.
- Fügen Sie Ihre HTTPS-Endpoint-URL ein.
- Wählen Sie die Event-Typen aus, die Sie empfangen möchten.
- Wählen Sie aus, von welchen Agenten Sie Events empfangen möchten.
- Klicken Sie auf Speichern.
💡 Tipp: Verwenden Sie die Test-Schaltfläche, um einen Beispiel-Payload an Ihren Endpoint zu senden. So bestätigen Sie, dass Ihr Server Anfragen empfangen kann, bevor echte Events ausgelöst werden.
Den Payload verstehen
Jede Webhook-Zustellung sendet ein JSON-Objekt mit drei Feldern auf oberster Ebene und einem verschachtelten data-Objekt mit dem vollständigen Kontext.
Felder der obersten Ebene:
| Feld | Beschreibung | Beispiel |
|---|---|---|
id | Eindeutige Zustellungs-ID (als Idempotenz-Schlüssel verwendet) | df313559-7cb1-... |
type | Der Event-Typ | activity.connection.accepted.v1 |
timestamp | Zeitpunkt des Events (ISO 8601) | 2026-02-06T05:05:36+01:00 |
Das data-Objekt enthält folgende Abschnitte:
| Abschnitt | Was er enthält |
|---|---|
data.agent | Name Ihres Agenten, Unternehmensdetails, Services, Markenstimme und Vertriebsplaybook |
data.campaign | Kampagnen-ID, Name, Status, Ziel, Produktseiten-URL, Landingpage-URL und Kampagnentyp |
data.campaignContact | Kontaktstatus in der Kampagne (z.B. invitation_send), letzte Aktivitätsdetails und Terminierungsstatus |
data.threadBox | Vollständige Namen von Absender und Kontakt, Tag-Array, Gesprächsstatus, Fit-Score, KI-Begründung, Persona-Name und Antwortstatus |
data.sender | Vollständiges LinkedIn-Profil des Absenderkontos, Wissensdatenbank-Kontaktinfos und MBTI-Persönlichkeitsanalyse |
data.contact | LinkedIn-Profil des Prospects, Überschrift, Zusammenfassung, Standort, Fähigkeiten, aktuelle Unternehmen und MBTI-Analyse |
data.messages | Array der Nachrichten im Gesprächsthread |
Sicherheits-Header bei jeder Zustellung:
| Header | Beschreibung |
|---|---|
webhook-signature | HMAC-Signatur zur Überprüfung, dass die Anfrage von QuantumOutbound stammt |
webhook-timestamp | Unix-Zeitstempel des Payload-Versands |
webhook-idempotency-key | Eindeutiger Schlüssel zur Vermeidung doppelter Verarbeitung |
webhook-key-id | Identifiziert den verwendeten Signaturschlüssel |
💡 Tipp: Der vollständige Payload ist umfangreich und enthält den gesamten Agentenkontext. Senden Sie zuerst einen Test-Webhook an Ihren Endpoint und verwenden Sie dann dieses JSON, um nur die Felder zu mappen, die Sie in Ihrem Handler benötigen.
Zustellungsverlauf prüfen
Sie können direkt in der App überprüfen, ob ein Webhook ausgelöst wurde, und den Zustellungsstatus einsehen. Gehen Sie zu Einstellungen → Webhooks, um aktuelle Zustellungen, deren Statuscodes und Zeitstempel zu sehen.
Häufige Fehler
„Der Test funktioniert, aber echte Events werden nicht ausgelöst"
Stellen Sie sicher, dass Sie eine aktive Kampagne haben, in der Prospects den Workflow durchlaufen. Webhooks werden ausgelöst, wenn das System eine Aktion durchführt (Einladung sendet, Nachricht sendet, Antwort erhält, Thread taggt) oder wenn Sie manuell einen Tag ändern. Wenn keine Aktivität stattfindet, gibt es keine Events zum Senden.
„Ich erhalte Events, aber im Payload fehlen Felder"
Der Payload variiert leicht je nach Event-Typ. Ein activity.invitation.sent.v1-Event enthält beispielsweise keine antwortbezogenen Felder. Prüfen Sie den Test-Payload für Ihren spezifischen Event-Typ, um zu sehen, welche Felder enthalten sind.
„Der Payload ist sehr groß"
Das ist normal. Jede Zustellung enthält den vollständigen Agentenkontext (Services, Vertriebsplaybook, Markenstimme), damit Ihr Handler alles hat, was er braucht, um das Event zu routen und zu verarbeiten. Parsen Sie nur die Felder, die Sie benötigen.
Wichtige Erkenntnisse
- Webhooks senden Echtzeitdaten an Ihren Server, wenn Events eintreten — sowohl automatisierte Kampagnenaktionen als auch manuelle Änderungen.
- Fünf Event-Typen decken den gesamten Outreach-Lebenszyklus ab: Einladung gesendet, Verbindung akzeptiert, Nachricht gesendet, Nachricht empfangen und Tag aktualisiert.
- Der Payload enthält den vollständigen Agenten-, Kampagnen- und Kontaktkontext in einer verschachtelten JSON-Struktur.
- Sicherheits-Header ermöglichen die Überprüfung, dass jede Zustellung von QuantumOutbound stammt.
- Beginnen Sie mit einem Test-Webhook, um die vollständige Payload-Struktur zu erfassen, bevor Sie Ihren Handler entwickeln.