Zum Inhalt springen

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.

  • 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
  1. Öffne Einstellungen › Integrationen.
  2. Klicke bei Webhooks auf Webhook hinzufügen.
  3. 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.
  4. Gib eine Beschreibung ein, an der du später erkennst, wofür der Webhook ist.
  5. Wähle die Ereignisse, über die ioumi informieren soll.
  6. Klicke auf Hinzufügen.

In der Liste kannst du einen Webhook jederzeit bearbeiten, vorübergehend deaktivieren oder löschen.

BereichEreignisse
Verträgeerstellt, versendet, angesehen, unterschrieben, abgelehnt, storniert, abgelaufen
Zahlungenerfolgreich, fehlgeschlagen
Rechnungenerstellt
Gutschriftenerstellt
Kontakteerstellt, 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.

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.

Jede Nachricht ist ein POST mit JSON und diesen Headern:

HeaderInhalt
X-Webhook-Eventdas Ereignis, zum Beispiel deal.signed
X-Webhook-IDeindeutige ID der Nachricht, bei Wiederholungen gleich
X-Webhook-Attemptder wievielte Zustellversuch es ist
X-Webhook-SignatureZeitstempel und Signatur im Format t=…,v1=…

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-ID deshalb nur einmal.
  • Schnell antworten: Antworte sofort mit einem 2xx-Status und erledige aufwendige Arbeit danach im Hintergrund.