Pipedrive Webhooks und API: Der Praxis-Guide auf Deutsch

Wer Pipedrive mit anderen Systemen verbinden will, landet früher oder später bei zwei Begriffen: API und Webhooks. Die klingen technisch, sind im Kern aber einfach. Dieser Guide erklärt beides in Klartext und zeigt, worauf es bei einer Anbindung ankommt, die auch nach Monaten noch zuverlässig läuft.

API und Webhook: der Unterschied in einem Satz

Die API ist der Weg, auf dem ihr Pipedrive aktiv etwas fragt oder sagt: “Gib mir alle Deals dieser Woche” oder “Setze diesen Deal auf gewonnen”. Ihr müsst die Anfrage starten.

Ein Webhook dreht das um: Pipedrive meldet sich bei euch, sobald etwas passiert. Sobald ein Deal die Phase wechselt, schickt Pipedrive automatisch eine Nachricht an eine von euch hinterlegte Adresse. Ihr müsst nicht ständig nachfragen.

Faustregel: Für Reaktionen in Echtzeit nehmt ihr Webhooks. Für gezielte Abfragen oder größere Datenmengen die API.

Der API-Token

Jede API-Anfrage braucht eine Authentifizierung. Der persönliche API-Token liegt in den Pipedrive-Einstellungen unter eurem Profil im Bereich Persönliche Einstellungen, Reiter API.

Ein wichtiger Punkt, der oft unterschätzt wird: Dieser Token hat dieselben Rechte wie der Nutzer, dem er gehört. Wenn ihr eine dauerhafte Integration baut, hängt sie am Account einer Person. Verlässt diese Person das Unternehmen und wird ihr Account deaktiviert, steht eure Integration still. Deshalb empfiehlt sich für produktive Anbindungen ein eigener technischer Nutzer statt eines persönlichen Accounts.

Webhooks: Version 1 und Version 2

Pipedrive hat die Webhooks überarbeitet. Version 2 ist die aktuelle und solltet ihr für neue Anbindungen nehmen. Sie ist zuverlässiger, reduziert doppelte und fehlende Auslöser und liefert bessere Möglichkeiten zur Fehlersuche. Außerdem deckt sie mehr Objekttypen ab, darunter Leads, Projekte und Aufgaben.

Was steht in einem Webhook drin?

Ein Webhook der Version 2 hat drei Hauptteile:

• meta: Informationen zum Ereignis selbst, also welche Aktion (anlegen, ändern, löschen), welcher Objekttyp, Zeitstempel und welcher Nutzer es ausgelöst hat.
• data: der aktuelle Stand des Objekts, also wie der Deal oder die Person nach der Änderung aussieht.
• previous: nur die Felder, die sich geändert haben, mit ihrem vorherigen Wert.

Das previous-Feld ist Gold wert: Damit könnt ihr genau erkennen, was sich geändert hat, ohne den alten Stand selbst speichern zu müssen. Beispiel: Ein Deal wechselt die Phase. In data steht die neue Phase, in previous die alte. Eure Automatisierung kann darauf gezielt reagieren.

Welche Ereignisse gibt es?

Drei Aktionen lösen einen Webhook aus: create (angelegt), change (geändert) und delete (gelöscht). Ihr könnt einen Webhook auf einen bestimmten Objekttyp und eine bestimmte Aktion einschränken, oder mit einer Wildcard auf alles hören.

Einen Webhook anlegen

Zwei Wege:

1. Über die Oberfläche: in den Pipedrive-Einstellungen unter Tools und Apps, Bereich Webhooks.
2. Über die API: mit einem POST auf /v1/webhooks. Pflichtangaben sind die subscription_url (eure öffentlich erreichbare Adresse), event_action, event_object und ein name. Die version ist optional und steht inzwischen standardmäßig auf 2.0.

Damit eure Adresse nicht offen im Netz hängt, könnt ihr eine einfache Absicherung per HTTP-Basic-Auth mitgeben (http_auth_user und http_auth_password). Pipedrive sendet diese dann bei jedem Aufruf mit, und ihr könnt auf eurer Seite prüfen, ob der Aufruf wirklich von Pipedrive kommt.

Worauf es bei einer stabilen Anbindung ankommt

Eine Anbindung zu bauen ist das eine. Eine zu bauen, die auch in einem halben Jahr noch verlässlich läuft, das andere. Drei Punkte aus der Praxis:

• Doppelte Zustellungen einplanen. Auch mit Version 2 kann ein Ereignis in seltenen Fällen mehr als einmal ankommen. Eure Verarbeitung muss damit umgehen, ohne doppelt zu handeln. Das heißt: vor jeder Schreib-Aktion prüfen, ob ihr dieses Ereignis schon verarbeitet habt.
• Schnell antworten, langsam arbeiten. Nehmt den Webhook entgegen, bestätigt ihn sofort und erledigt die eigentliche Arbeit danach. Wer den Webhook erst nach langer Verarbeitung beantwortet, riskiert Wiederholungs-Zustellungen.
• Fehler sichtbar machen. Loggt, was rein- und rausgeht. Wenn eine Anbindung leise ausfällt, merkt es oft monatelang niemand, bis Daten fehlen.

Wann lohnt sich der Aufwand?

Webhooks und API sind kein Selbstzweck. Sie lohnen sich, sobald ein wiederkehrender Handgriff zwischen Pipedrive und einem anderen System sonst manuell passieren müsste: Rechnung aus gewonnenem Deal, Aufgabe im Projekt-Tool, Benachrichtigung ins Team-Chat. Für viele dieser Fälle braucht ihr nicht einmal Code, sondern könnt ein Automatisierungs-Werkzeug dazwischenschalten. Mehr dazu in unserem Vergleich von Pipedrives eingebauten Automatisierungen mit n8n, Make und Zapier.

Wenn ihr eine konkrete Anbindung plant und unsicher seid, ob Webhook, API oder ein fertiges Werkzeug der richtige Weg ist: als Pipedrive Authorized Partner bauen wir genau solche Integrationen und sagen euch ehrlich, wann sich der eigene Aufbau lohnt und wann nicht.