Webhooks verwenden

SalesMind AI kann Ereignisdaten in dem Moment an Ihren Server senden, in dem etwas passiert — eine Kontaktanfrage geht raus, ein Interessent nimmt an, eine Nachricht wird gesendet oder empfangen, oder eine Unterhaltung wird getaggt. Statt die API abzufragen, erhält Ihr Endpunkt eine POST-Anfrage mit dem vollständigen Kontext.

Diese Anleitung zeigt Ihnen, wie Sie einen Webhook-Endpunkt einrichten, die gewünschten Events auswählen und die Nutzlast verarbeiten.

Voraussetzungen

• Ein SalesMind AI-Konto mit mindestens einem aktiven Sender
• Ein öffentlich erreichbarer HTTPS-Endpunkt, der POST-Anfragen empfangen kann

Wie Webhooks funktionieren

SalesMind AI löst einen Webhook aus, sobald ein relevantes Ereignis in einem Unterhaltungs-Thread in Ihrem Posteingang passiert — ausgelöst durch eine Kampagnenaktion oder eine manuelle Änderung, die Sie in der Oberfläche vornehmen. Jedes Ereignis sendet eine HTTP-POST-Anfrage an die von Ihnen eingerichtete URL.

Verfügbare Ereignistypen

Ereignistyp	Wird ausgelöst, wenn…
activity.invitation.sent.v1	Eine Kontaktanfrage an einen Interessenten gesendet wird
activity.connection.accepted.v1	Ein Interessent Ihre Kontaktanfrage annimmt
activity.message.sent.v1	Eine Nachricht an einen Interessenten gesendet wird (inklusive automatischer Kampagnennachrichten und Follow-ups)
activity.message.received.v1	Ein Interessent auf Ihre Unterhaltung antwortet
activity.threadbox.tags.update.v1	Ein Tag in einem Unterhaltungs-Thread hinzugefügt oder entfernt wird

Diese fünf activity.*-Events sind das, was ein normales Konto abonnieren und empfangen kann. Ein sechstes Event, user.register.v1, existiert, ist aber nur für Admins — normale Konten empfangen es nie, und es wird automatisch entfernt, wenn Sie versuchen, es zu abonnieren. webhook.test.v1 ist ein einmaliges Event, das über die Schaltfläche Test gesendet wird, nichts, das Sie abonnieren.

Ihren Webhook-Endpunkt einrichten

1. Klicken Sie in der linken Seitenleiste unten auf das Einstellungen-Zahnrad.
2. Klicken Sie auf Webhooks.
3. Fügen Sie Ihre HTTPS-Endpunkt-URL ein.
4. Wählen Sie die Ereignistypen aus, die Sie empfangen möchten.
5. Wählen Sie, von welchen Agenten Sie Events empfangen möchten.
6. Klicken Sie auf Speichern.

💡 Tipp: Nutzen Sie die Schaltfläche Test, um eine Beispiel-Nutzlast an Ihren Endpunkt zu senden. So bestätigen Sie, dass Ihr Server Anfragen empfangen kann, bevor echte Events ausgelöst werden.

Endpunkte über die API verwalten

Sie können Webhook-Endpunkte über die API statt über die Oberfläche verwalten. Jeder Endpunkt braucht Ihren X-API-KEY-Header und liegt unter https://api.sales-mind.ai//v1/webhooks.

Methode	Endpunkt	Zweck
POST	/v1/webhooks/endpoints	Einen neuen Endpunkt registrieren
GET	/v1/webhooks/endpoints	Ihre Endpunkte auflisten
GET	/v1/webhooks/endpoints/{id}	Einen Endpunkt abrufen
DELETE	/v1/webhooks/endpoints/{id}	Einen Endpunkt löschen
GET	/v1/webhooks/endpoints/{id}/rotate-secret	Ein neues Signatur-Secret abrufen
PUT	/v1/webhooks/endpoints/{id}/suspend	Einen Endpunkt aussetzen oder fortsetzen
GET	/v1/webhooks/events	Die abonnierbaren Events auflisten
PUT	/v1/webhooks/endpoints/{id}/events	Die abonnierten Events ändern
GET	/v1/webhooks/endpoints/{id}/test	Eine Test-Zustellung senden

⚠️ Die Registrierung gibt Ihr Signatur-Secret nicht zurück. Nachdem Sie einen Endpunkt registriert haben, rufen Sie rotate-secret auf, um das Secret zu erhalten, mit dem Sie Zustellungen verifizieren.

Ihr Endpunkt muss eine öffentliche HTTPS-URL sein. SalesMind AI prüft das bei der Zustellung eines Events, nicht bei der Registrierung — eine Nicht-HTTPS- oder private URL wird also zunächst akzeptiert und scheitert dann bei der Zustellung.

Die Nutzlast verstehen

Jede Webhook-Zustellung sendet ein JSON-Objekt mit drei Feldern auf oberster Ebene und einem verschachtelten data-Objekt, das den vollständigen Kontext enthält.

Felder auf oberster Ebene:

Feld	Beschreibung	Beispiel
id	Eindeutige Zustellungs-ID (als Idempotenzschlüssel verwendet)	df313559-7cb1-...
type	Der Ereignistyp	activity.connection.accepted.v1
timestamp	Wann das Ereignis passierte (ISO 8601)	2026-02-06T05:05:36+01:00

Das data-Objekt enthält diese Abschnitte:

Abschnitt	Was er enthält
data.agent	Ihr Agentenname, Firmendetails, Leistungen, Marken-Tonalität und Sales-Playbook
data.campaign	Kampagnen-ID, Name, Status, Ziel, Produktseiten-URL, Landingpage-URL und Kampagnentyp
data.campaignContact	Kontaktstatus in der Kampagne (z. B. invitation_send), Details der letzten Aktivität und Beendet-Flag
data.threadBox	Vollständige Namen von Sender und Kontakt, Tags-Array, Unterhaltungsstatus, Fit-Score, KI-Begründung, Persona-Name und Antwortstatus
data.sender	Vollständiges LinkedIn-Profil des sendenden Kontos, Kontaktdaten aus der Wissensdatenbank und MBTI-Persönlichkeitsanalyse
data.contact	LinkedIn-Profil des Interessenten, Überschrift, Zusammenfassung, Standort, Fähigkeiten, aktuelle Unternehmen und MBTI-Analyse
data.messages	Array der Nachrichten im Unterhaltungs-Thread

💡 Tipp: Die vollständige Nutzlast ist groß und enthält den kompletten Agentenkontext. Senden Sie zuerst einen Test-Webhook an Ihren Endpunkt und nutzen Sie dann dieses JSON, um in Ihrem Handler nur die benötigten Felder zuzuordnen.

Die Signatur verifizieren

Jede Zustellung trägt vier Header, mit denen Sie bestätigen können, dass sie wirklich von SalesMind AI kam:

Header	Wert
Webhook-Signature	Base64-kodierter HMAC-SHA256 der signierten Zeichenkette
Webhook-Timestamp	Unix-Epoch-Sekunden, in der signierten Zeichenkette verwendet
Webhook-Idempotency-Key	{eventId}:{endpointId} — nutzen Sie ihn, um doppelte Zustellungen zu verwerfen
Webhook-Key-Id	current — welches Signatur-Secret verwendet wurde

Die signierte Zeichenkette ist:

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

Signieren Sie den Wert aus dem Webhook-Timestamp-Header, nicht das ISO-Feld timestamp im Body — sie sind unterschiedlich.

So verifizieren Sie eine Zustellung:

1. Lesen Sie den rohen Request-Body, den Webhook-Timestamp-Header und den Webhook-Signature-Header.
2. Berechnen Sie den SHA-256-Hex-Digest des rohen Bodys und bilden Sie dann {Webhook-Timestamp}.{endpointId}.{sha256_hex}.
3. Berechnen Sie Base64(HMAC-SHA256(diese Zeichenkette, Ihr Endpunkt-Secret)) und vergleichen Sie das Ergebnis mit Webhook-Signature per konstant-zeitlichem Vergleich.
4. Optional: Verwerfen Sie die Zustellung, wenn Webhook-Timestamp älter ist als ein von Ihnen gewähltes Zeitfenster (zum Beispiel 5 Minuten).

💡 Das 5-Minuten-Replay-Fenster ist eine Prüfung, die Sie auf Ihrer Seite hinzufügen. SalesMind AI erzwingt sie nicht.

⚠️ Aktualisieren Sie nach dem Rotieren Ihres Secrets Ihr gespeichertes Secret umgehend. SalesMind AI signiert immer mit dem aktuellen Secret, sodass Zustellungen sofort auf das neue Secret umstellen — es gibt auf der Signaturseite keine Übergangsfrist.

Zustellungsverlauf prüfen

Sie können direkt in der App prüfen, ob ein Webhook ausgelöst wurde, und dessen Zustellungsstatus einsehen. Gehen Sie zu Einstellungen → Webhooks, um die letzten Zustellungen, ihre Statuscodes und Zeitstempel zu sehen.

Sie können Zustellungen auch über die API abrufen:

Methode	Endpunkt	Zweck
GET	/v1/webhooks/deliveries	Zustellungen auflisten (Filter nach endpointId, status, type)
GET	/v1/webhooks/deliveries/{id}	Eine Zustellung inklusive Nutzlast abrufen
POST	/v1/webhooks/deliveries/{id}/replay	Eine Zustellung als neues Event erneut senden

Jede Zustellung hat einen Status: pending, delivered, failed oder suspended.

So funktionieren Zustellungsversuche:

• Jeder Versuch hat ein Timeout von 5 Sekunden.
• Eine 2xx-Antwort markiert die Zustellung als delivered und setzt den Fehlerzähler des Endpunkts zurück.
• Jede andere Antwort — oder ein Timeout — markiert sie als failed und wiederholt mit einem Backoff von 5, 10, 20, 60, dann 300 Sekunden (bis zu 5 Wiederholungen, also insgesamt 6 Versuche).
• Nach 10 aufeinanderfolgenden Fehlern setzt SalesMind AI den Endpunkt automatisch aus. Neue Events für einen ausgesetzten Endpunkt werden als suspended erfasst und übersprungen, bis Sie ihn fortsetzen.

Häufige Fehler

„Der Test funktioniert, aber echte Events werden nicht ausgelöst"

Stellen Sie sicher, dass Sie eine aktive Kampagne mit Interessenten haben, die den Workflow durchlaufen. Webhooks werden ausgelöst, wenn das System eine Aktion ausführt (eine Einladung sendet, eine Nachricht sendet, eine Antwort erhält, einen Thread taggt) oder wenn Sie manuell ein Tag ändern. Wenn keine Aktivität stattfindet, gibt es keine Events zu senden.

„Ich erhalte Events, aber der Nutzlast fehlen Felder"

Die Nutzlast variiert leicht je nach Ereignistyp. Ein activity.invitation.sent.v1-Event hat zum Beispiel keine antwortbezogenen Felder. Prüfen Sie die Test-Nutzlast für Ihren konkreten Ereignistyp, um zu sehen, welche Felder enthalten sind.

„Die Nutzlast ist sehr groß"

Das ist zu erwarten. Jede Zustellung enthält den vollständigen Agentenkontext (Leistungen, Sales-Playbook, Marken-Tonalität), damit Ihr Handler alles hat, um das Event zu routen und zu verarbeiten. Parsen Sie nur die Felder, die Sie brauchen.

„Meine Endpunkt-URL wurde akzeptiert, empfängt aber nie etwas"

Ihr Endpunkt muss eine öffentliche HTTPS-URL sein. SalesMind AI prüft das bei der Zustellung eines Events, nicht bei der Registrierung — eine Nicht-HTTPS- oder private URL wird also zunächst akzeptiert und scheitert dann bei der Zustellung. Prüfen Sie Ihren Zustellungsverlauf auf fehlgeschlagene Versuche.

Wichtige Erkenntnisse

• Webhooks schicken Echtzeitdaten an Ihren Server, wenn Ereignisse passieren — sowohl automatische Kampagnenaktionen als auch manuelle Änderungen.
• Ein normales Konto abonniert die fünf activity.*-Events; user.register.v1 ist nur für Admins und webhook.test.v1 ist nur das Test-Event.
• Verwalten Sie Endpunkte, Events und Zustellungen über die API unter https://api.sales-mind.ai//v1/webhooks — authentifizieren Sie sich mit X-API-KEY.
• Verifizieren Sie jede Zustellung mit den Headern Webhook-Signature und Webhook-Timestamp; das Signatur-Secret kommt aus rotate-secret, nicht aus der Registrierung.
• Zustellungen werden mit Backoff wiederholt, und ein Endpunkt wird nach 10 aufeinanderfolgenden Fehlern ausgesetzt — prüfen und wiederholen Sie über den Zustellungsverlauf.

FAQ

Welche Events kann mein Konto empfangen? Normale Konten empfangen die fünf activity.*-Events. user.register.v1 ist nur für Admins, und webhook.test.v1 ist nur das Test-Event.

Wie verifiziere ich, dass ein Webhook von SalesMind AI kam? Berechnen Sie die Signatur aus dem rohen Body und dem Webhook-Timestamp-Header neu und vergleichen Sie sie mit dem Webhook-Signature-Header. Siehe „Die Signatur verifizieren" oben.

Wie erhalte ich mein Signatur-Secret? Die Registrierung gibt es nicht zurück. Rufen Sie den rotate-secret-Endpunkt auf, um ein neues Secret zu erhalten, und aktualisieren Sie Ihre gespeicherte Kopie sofort.

Warum wurde mein Endpunkt ausgesetzt? SalesMind AI setzt einen Endpunkt nach zu vielen fehlgeschlagenen Zustellungen in Folge aus — standardmäßig 10. Beheben Sie das Problem auf Ihrem Server und setzen Sie den Endpunkt dann fort.

Kann ich einen verpassten Webhook erneut senden? Ja. Nutzen Sie den Replay-Endpunkt, um eine frühere Zustellung erneut als neues Event zu senden.

Meine URL wurde akzeptiert, aber es kommen keine Events an. Warum? Die HTTPS- und Public-URL-Prüfung läuft zur Zustellungszeit, nicht bei der Registrierung. Eine fehlerhafte URL wird zunächst akzeptiert und scheitert dann bei der Zustellung. Prüfen Sie Ihren Zustellungsverlauf.