Webhooks in ioumi einrichten und Ereignisse empfangen
Ein Webhook ist eine automatische Nachricht von ioumi an ein anderes Programm. Sobald in ioumi etwas passiert, zum Beispiel ein Vertrag unterschrieben wird oder eine Zahlung eingeht, schickt ioumi die Details sofort an eine Adresse deiner Wahl. Dein CRM, Make, Zapier, n8n oder dein eigenes System kann darauf reagieren, ohne ständig bei ioumi nachfragen zu müssen.
Der Unterschied zur API: Bei der API fragt dein System bei ioumi nach. Beim Webhook meldet sich ioumi von selbst. Mehr zur API in API.
Typische Anwendungsfälle
Abschnitt betitelt „Typische Anwendungsfälle“- Vertrag unterschrieben: Onboarding im Projekttool anlegen, Willkommensmail verschicken, Opportunity im CRM auf gewonnen setzen
- Zahlung fehlgeschlagen: Aufgabe im CRM anlegen oder dein Team im Chat informieren
- Rechnung erstellt: Rechnung automatisch an deine Buchhaltung weitergeben. Auf diesem Ereignis baut auch der Modus für Rechnungen aus deinem eigenen Rechnungsprogramm auf, siehe Externer Rechnungsmodus.
- Kontakt angelegt oder geändert: Kundendaten mit deinem CRM abgleichen
Webhook anlegen
Abschnitt betitelt „Webhook anlegen“- Öffne Einstellungen › Integrationen.
- Klicke bei Webhooks auf Webhook hinzufügen.
- Trage die URL ein, an die ioumi die Nachrichten schicken soll. In Make, Zapier oder n8n bekommst du diese Adresse, wenn du dort einen Webhook als Auslöser anlegst.
- Gib eine Beschreibung ein, an der du später erkennst, wofür der Webhook ist.
- Wähle die Ereignisse, über die ioumi informieren soll.
- Klicke auf Hinzufügen.
In der Liste kannst du einen Webhook jederzeit bearbeiten, vorübergehend deaktivieren oder löschen.
Die Ereignisse
Abschnitt betitelt „Die Ereignisse“| Bereich | Ereignisse |
|---|---|
| Verträge | erstellt, versendet, angesehen, unterschrieben, abgelehnt, storniert, abgelaufen |
| Zahlungen | erfolgreich, fehlgeschlagen |
| Rechnungen | erstellt |
| Gutschriften | erstellt |
| Kontakte | erstellt, aktualisiert, gelöscht |
Jede Nachricht enthält die Daten des betroffenen Vertrags, der Zahlung, der Rechnung oder des Kontakts. Welche Felder genau enthalten sind, steht in der API-Dokumentation unter Einstellungen › Integrationen › API-Dokumentation.
Welches Ereignis meldet den Vertragsabschluss?
Abschnitt betitelt „Welches Ereignis meldet den Vertragsabschluss?“Sobald dein Kunde den Vertrag unterschreibt, sendet ioumi das Ereignis „unterschrieben“ (deal.signed). Für Abläufe nach dem Vertragsabschluss, etwa Onboarding, Kurszugang oder den Status im CRM, ist das das richtige Ereignis.
Was passiert, wenn dein System nicht erreichbar ist?
Abschnitt betitelt „Was passiert, wenn dein System nicht erreichbar ist?“ioumi erwartet innerhalb von 30 Sekunden eine erfolgreiche Antwort. Kommt keine, versucht ioumi es automatisch erneut: Erstzustellung plus bis zu vier Wiederholungen nach 5 Minuten, 30 Minuten, 2 Stunden und 6 Stunden. Schlägt auch die letzte Wiederholung fehl, stellt ioumi diese Nachricht nicht weiter zu. Achte deshalb darauf, dass die Adresse dauerhaft erreichbar ist.
Für Entwickler
Abschnitt betitelt „Für Entwickler“Jede Nachricht ist ein POST mit JSON und diesen Headern:
| Header | Inhalt |
|---|---|
X-Webhook-Event | das Ereignis, zum Beispiel deal.signed |
X-Webhook-ID | eindeutige ID der Nachricht, bei Wiederholungen gleich |
X-Webhook-Attempt | der wievielte Zustellversuch es ist |
X-Webhook-Signature | Zeitstempel und Signatur im Format t=…,v1=… |
Darauf solltest du achten
Abschnitt betitelt „Darauf solltest du achten“Damit deine Anbindung sicher und zuverlässig läuft, beachte beim Empfangen drei Punkte:
- Signatur prüfen: Die Signatur ist ein HMAC-SHA256 aus Zeitstempel und JSON-Inhalt, erstellt mit dem Webhook-Secret. Prüfe sie, bevor du die Nachricht verarbeitest. So stellst du sicher, dass sie wirklich von ioumi kommt. Wie du das Secret erhältst und die Signatur prüfst, beschreibt die API-Dokumentation.
- Doppelte Nachrichten erkennen: Geht eine Antwort unterwegs verloren, kann dieselbe Nachricht ein zweites Mal ankommen. Verarbeite jede
X-Webhook-IDdeshalb nur einmal. - Schnell antworten: Antworte sofort mit einem 2xx-Status und erledige aufwendige Arbeit danach im Hintergrund.