Webhooks

Webhooks ermöglichen die Echtzeitkommunikation zwischen Pelatis und externen Systemen. Ausgehende Webhooks benachrichtigen deine Systeme über Ereignisse in Pelatis. Eingehende Webhooks lassen externe Systeme Daten an Pelatis senden.

Ausgehende Webhooks

Ausgehende Webhooks senden HTTP-POST-Anfragen an eine von dir angegebene URL, wenn bestimmte Ereignisse in deinem CRM auftreten.

Ausgehenden Webhook einrichten

  1. Gehe zu Einstellungen > Webhooks
  2. Klicke auf Webhook erstellen
  3. Gib die Ziel-URL ein (muss HTTPS sein)
  4. Wähle die Events, die du abonnieren möchtest
  5. Gib optional ein Secret für die Signaturverifizierung ein
  6. Klicke auf Speichern

Verfügbare Events

Event Löst aus, wenn
lead.created Ein neuer Lead erstellt wird
lead.updated Die Felder eines Leads aktualisiert werden
lead.deleted Ein Lead soft-gelöscht wird
lead.stage_changed Ein Lead die Stufe wechselt
lead.assigned Der zugewiesene Benutzer eines Leads sich ändert
contact.created Ein neuer Kontakt erstellt wird
contact.updated Ein Kontakt aktualisiert wird
contact.deleted Ein Kontakt gelöscht wird
opportunity.created Eine neue Chance erstellt wird
opportunity.updated Eine Chance aktualisiert wird
task.created Eine neue Aufgabe erstellt wird
task.completed Eine Aufgabe als erledigt markiert wird
note.created Eine Notiz zu einem Lead hinzugefügt wird
form.submitted Eine Formulareinreichung eingeht

Payload-Format

Jede Webhook-Zustellung sendet eine JSON-POST-Anfrage mit dieser Struktur:

{
  "event": "lead.stage_changed",
  "timestamp": "2026-03-24T14:30:00Z",
  "organization_id": "org_abc123",
  "data": {
    "id": "lead_xyz789",
    "name": "Acme Corp",
    "stage": "Angebot",
    "previous_stage": "Qualifiziert",
    "assigned_to": "user_456",
    "updated_at": "2026-03-24T14:30:00Z"
  }
}

Das data-Objekt enthält den vollständigen aktuellen Zustand der betroffenen Entität sowie relevante Kontextfelder wie previous_stage bei Änderungs-Events.

Signaturverifizierung

Wenn du ein Webhook-Secret festlegst, fügt Pelatis eine Signatur im X-Webhook-Signature-Header ein. Die Signatur ist ein HMAC-SHA256-Hash des rohen Request-Body mit deinem Secret:

X-Webhook-Signature: sha256=a1b2c3d4e5f6...

Verifiziere die Signatur in deiner empfangenden Anwendung, um zu bestätigen, dass die Anfrage von Pelatis stammt.

Retry-Logik

Wenn dein Endpoint einen Nicht-2xx-Statuscode zurückgibt oder nicht innerhalb von 10 Sekunden antwortet, wiederholt Pelatis die Zustellung:

Versuch Verzögerung
1. Retry 1 Minute
2. Retry 5 Minuten
3. Retry 30 Minuten
4. Retry 2 Stunden
5. Retry 12 Stunden

Nach 5 fehlgeschlagenen Versuchen wird die Zustellung als fehlgeschlagen markiert. Du kannst fehlgeschlagene Zustellungen einsehen und manuell erneut auslösen.

Zustellungsprotokoll

Jeder Webhook hat ein Zustellungsprotokoll, das zeigt:

  • Zeitstempel jedes Zustellungsversuchs
  • Zurückgegebener HTTP-Statuscode
  • Antwortzeit
  • Erfolgs- oder Fehlerstatus

Eingehende Webhooks

Eingehende Webhooks lassen externe Systeme Daten an Pelatis senden. Jeder eingehende Webhook hat eine eindeutige URL, die POST-Anfragen akzeptiert.

Eingehenden Webhook einrichten

  1. Gehe zu Einstellungen > Webhooks > Eingehend
  2. Klicke auf Eingehenden Webhook erstellen
  3. Gib einen Namen ein (z.B. "Website-Leadformular")
  4. Konfiguriere die Feldzuordnung — lege fest, wie eingehende JSON-Felder auf Pelatis-Lead-Felder abgebildet werden
  5. Setze optional eine Pipeline und Stufe für erstellte Leads
  6. Kopiere die generierte Webhook-URL
  7. Konfiguriere dein externes System, um POST-Anfragen an diese URL zu senden

URL-Format für eingehende Webhooks

https://app.pelatiscrm.com/api/webhooks/incoming/whk_abc123

Authentifizierung

Eingehende Webhooks können mit einem Bearer Token gesichert werden:

curl -X POST \
  -H "Authorization: Bearer dein_token_hier" \
  -H "Content-Type: application/json" \
  -d '{"company": "Acme", "email": "[email protected]"}' \
  https://app.pelatiscrm.com/api/webhooks/incoming/whk_abc123

Wenn ein Token konfiguriert ist, erhalten Anfragen ohne gültigen Token 401 Unauthorized.

Feldzuordnung

Konfiguriere, wie eingehende JSON-Felder auf Pelatis-Felder abgebildet werden:

Eingehendes Feld Wird zugeordnet zu
company Lead-Name
email Lead-E-Mail
phone Lead-Telefon
contact_name Kontaktname
contact_email Kontakt-E-Mail
message Notizinhalt

Du kannst auch benutzerdefinierte Felder zuordnen, indem du deren Feldschlüssel referenzierst.

Antwortformat

Erfolgreiche eingehende Webhooks geben zurück:

{
  "success": true,
  "lead_id": "lead_xyz789"
}

Webhooks verwalten

Deaktivieren

Schalte einen Webhook in der Listenansicht aus. Deaktivierte Webhooks senden und empfangen nicht mehr, behalten aber ihre Konfiguration.

Testen

Nutze den Test senden-Button bei jedem ausgehenden Webhook, um einen Beispiel-Payload an deinen Endpoint zu senden. So kannst du deine Integration überprüfen, bevor echte Events auslösen.

Löschen

Lösche einen Webhook aus der Listenansicht. Bei ausgehenden Webhooks werden ausstehende Retries abgebrochen. Bei eingehenden Webhooks nimmt die URL sofort keine Anfragen mehr an.

Best Practices

  • Signaturen immer verifizieren bei ausgehenden Webhooks, um gefälschte Anfragen zu verhindern.
  • Schnell antworten. Dein Endpoint sollte innerhalb weniger Sekunden 200 zurückgeben. Aufwändige Verarbeitung sollte asynchron nach Empfangsbestätigung erfolgen.
  • HTTPS verwenden. Ausgehende Webhooks erfordern HTTPS-Endpoints.
  • Eingehende Payloads protokollieren. Logge bei neuen eingehenden Webhooks die rohen Payloads einige Tage lang, um die Feldzuordnung zu verifizieren.
  • Zustellungsfehler überwachen. Prüfe das Zustellungsprotokoll regelmäßig. Wiederholte Fehler können auf ein Problem mit deinem Endpoint hinweisen.