1. Was ist ein Webhook?
Im API-Guide haben wir gelernt: Mit der API fragt man aktiv nach – man schickt eine Anfrage und bekommt eine Antwort. Das ist wie in einem Restaurant zur Kellnerin gehen und fragen: "Was haben Sie heute noch auf der Karte?"
Ein Webhook funktioniert genau andersherum: Man sagt der Kellnerin einmalig: "Wenn ein neues Tagesgericht hereinkommt – sag mir bitte sofort Bescheid!" Ab dann muss man nicht mehr immer wieder nachfragen. Man wird automatisch benachrichtigt, sobald etwas passiert.
1.1 Das Haustürklingel-Prinzip
Stell dir vor, du wartest auf ein Paket. Du könntest alle 10 Minuten zur Haustür gehen und nachschauen, ob das Paket schon da ist. Das ist die API-Methode – ständiges aktives Nachfragen.
Oder du installierst eine Türklingel. Sobald der Paketbote kommt, klingelt er – und du wirst sofort benachrichtigt. Du musst vorher nichts tun außer die Klingel einzurichten. Das ist der Webhook.
| 🔁 API (aktives Abfragen) | 🪝 Webhook (passives Warten) |
|---|---|
| Ich frage regelmäßig nach | Billomat meldet sich von selbst |
| Wie: "Gibt es neue Rechnungen?" | Wie: "Neue Rechnung erstellt – hier sind die Daten" |
| Verbraucht API-Kontingent | Verbraucht kein API-Kontingent |
| Kann Daten verpassen (zwischen zwei Abfragen) | Kein Datenverlust – sofortige Benachrichtigung |
| Gut für: einmalige Abfragen | Gut für: Echtzeit-Benachrichtigungen |
2. Wie funktioniert ein Webhook genau?
2.1 Der Ablauf Schritt für Schritt
Hier ist, was technisch passiert – am Beispiel einer neu erstellten Rechnung:
| Schritt 1: Einrichtung (einmalig) |
Der Kunde richtet in Billomat einen Webhook ein: Er gibt an, welches Ereignis ihn interessiert und wohin Billomat die Nachricht schicken soll. → Ereignis: invoice.create (Rechnung erstellt) → Ziel-URL: https://mein-system.de/empfang |
| Schritt 2: Ereignis tritt ein |
Jemand erstellt eine neue Rechnung in Billomat – entweder manuell oder über die API. → Billomat erkennt: Das Ereignis invoice.create ist eingetreten |
| Schritt 3: Billomat schickt automatisch eine Nachricht |
Billomat sendet einen sogenannten POST-Request an die eingerichtete Ziel-URL. → Die Nachricht enthält alle Daten der neuen Rechnung (Rechnungsnummer, Betrag, Kunde etc.) → Im Header steht: X-Billomat-Webhook-Event: invoice.create |
| Schritt 4: Das Zielsystem empfängt und verarbeitet |
Das System des Kunden empfängt die Nachricht und verarbeitet sie automatisch. → z. B. wird der Kunde im CRM als "Rechnung erhalten" markiert → z. B. wird die Rechnung in die Buchhaltung übertragen |
| Schritt 5: Bestätigung zurückschicken |
Das Zielsystem muss innerhalb von 10 Sekunden mit dem Status 200 antworten. → Tut es das nicht → Billomat versucht es erneut → Schlagen alle Versuche fehl → Webhook wird deaktiviert |
2.2 Wie sieht die Nachricht aus, die Billomat verschickt?
Billomat schickt immer eine Nachricht im XML-Format. Im Header ("Briefumschlag") steht, was passiert ist – im Body ("Briefinhalt") stehen alle Daten dazu:
Der Header (Briefumschlag) enthält:
| X-Billomat-Webhook-Id: 1 | (Welcher Webhook hat gefeuert?) |
| X-Billomat-Webhook-Request-Id: 510 | (Eindeutige ID dieser Nachricht) |
| X-Billomat-Webhook-Event: invoice.create | (Welches Ereignis?) |
| User-Agent: Billomat-Webhook | (Absender: Billomat) |
| Content-Type: application/xml | (Format der Nachricht) |
Der Body (Briefinhalt) enthält alle Rechnungsdaten:
<?xml version="1.0" encoding="UTF-8"?>
<invoice>
<id>1</id>
<invoice_number>RE123</invoice_number>
<client_id>123</client_id>
<status>OPEN</status>
<date>2024-10-14</date>
<due_date>2024-10-24</due_date>
<total_gross>1190.00</total_gross>
<total_net>1000.00</total_net>
</invoice>
💡Tipp: Woher weiß ich, welches Ereignis ausgelöst wurde? Immer im Header nachschauen: X-Billomat-Webhook-Event zeigt genau, was passiert ist. invoice.create = Rechnung erstellt, invoice.status = Status der Rechnung hat sich geändert usw.
3. Alle Billomat-Webhook-Ereignisse (Events)
Für jedes dieser Ereignisse kann ein Webhook eingerichtet werden. Das Format lautet immer: bereich.aktion
3.1 Rechnungen (Invoices)
Ereignis |
Bedeutung |
Wann wird es ausgelöst? |
invoice.create |
Rechnung erstellt |
Eine neue Rechnung wurde angelegt |
invoice.update |
Rechnung geändert |
Daten einer Rechnung wurden bearbeitet |
invoice.status |
Status geändert |
z.B. von DRAFT zu OPEN, oder zu PAID |
invoice.send |
Rechnung versendet |
Die Rechnung wurde per E-Mail verschickt |
invoice.delete |
Rechnung gelöscht |
Eine Rechnung wurde gelöscht |
invoice_comment.create |
Kommentar erstellt |
Ein Kommentar zur Rechnung wurde hinzugefügt |
invoice_comment.delete |
Kommentar gelöscht |
Ein Kommentar wurde entfernt |
invoice_payment.create |
Zahlung verbucht |
Eine Zahlung wurde zur Rechnung hinzugefügt |
invoice_payment.delete |
Zahlung gelöscht |
Eine verbuchte Zahlung wurde entfernt |
3.2 Angebote (Offers)
Ereignis |
Bedeutung |
offer.create |
Angebot erstellt |
offer.update |
Angebot geändert |
offer.status |
Status des Angebots geändert |
offer.send |
Angebot versendet |
offer.delete |
Angebot gelöscht |
offer_comment.create |
Kommentar zum Angebot erstellt |
offer_comment.delete |
Kommentar zum Angebot gelöscht |
3.3 Kunden (Clients)
Ereignis |
Bedeutung |
client.create |
Neuer Kunde angelegt |
client.update |
Kundendaten geändert |
client.delete |
Kunde gelöscht |
3.4 Weitere wichtige Ereignisse
Bereich |
Ereignis |
Bedeutung |
Abo-Rechnungen |
recurring.create / .update / .delete |
Abo erstellt / geändert / gelöscht |
Mahnungen |
reminder.create / .update / .status / .send / .delete |
Mahnung erstellt / Status geändert / versendet |
Gutschriften |
credit_note.create / .update / .status / .send / .delete |
Gutschrift erstellt / Status geändert / versendet |
Auftragsbestätigungen |
confirmation.create / .update / .status / .send / .delete |
AB erstellt / geändert / versendet |
Lieferscheine |
delivery_note.create / .update / .status / .send / .delete |
Lieferschein erstellt / versendet |
Artikel |
article.create / .update / .delete |
Artikel hinzugefügt / geändert / gelöscht |
Eingangsrechnungen |
incoming_invoice.create / .update / .delete |
Eingangsrechnung erstellt / gelöscht |
4. Webhook einrichten in Billomat
Webhooks werden direkt im Billomat-Account eingerichtet – ohne Programmierung. So geht es:
| Schritt 1: In Billomat einloggen | Den Billomat-Account öffnen (z.B. billomatid.billomat.net). |
| Schritt 2: Zu den Webhooks navigieren | → Einstellungen → Administration → Webhooks |
| Schritt 3: Neuen Webhook anlegen | Auf den Button 'Webhook hinzufügen' oder '+' klicken. |
| Schritt 4: Ereignis auswählen |
Aus der Liste das gewünschte Ereignis auswählen. → z.B. invoice.create für 'Neue Rechnung erstellt' → z.B. invoice.status für 'Rechnungsstatus geändert' |
| Schritt 5: Ziel-URL eingeben |
Die URL eingeben, an die Billomat die Nachricht schicken soll. → Das ist die URL des Kundensystems, das die Benachrichtigung empfangen soll |
| Schritt 6: Speichern |
Den Webhook speichern. Er ist sofort aktiv. → Ab jetzt: Sobald das Ereignis eintritt, schickt Billomat automatisch eine Nachricht! |
|
💡 Wichtig: Die Ziel-URL muss erreichbar sein! Die URL, die der Kunde einträgt, muss öffentlich aus dem Internet erreichbar sein – Billomat schickt die Nachricht von seinen Servern. Eine lokale Adresse wie 'localhost' oder '192.168.x.x' funktioniert NICHT. |
4.1 Webhook testen mit webhook.site
Möchte man schnell testen, ob ein Webhook korrekt feuert, gibt es einen einfachen Trick ohne technischen Aufwand:
| Schritt 1: webhook.site öffnen | Die Seite Webhook.site - Test, transform and automate Web requests and emails im Browser öffnen. |
| Schritt 2: Test-URL kopieren |
Auf der Seite erscheint automatisch eine einmalige Test-URL (z.B. https://webhook.site/abc-123). → Diese URL kopieren |
| Schritt 3: Als Ziel-URL in Billomat eintragen | In Billomat einen Webhook mit dieser Test-URL anlegen und das gewünschte Ereignis auswählen. |
| Schritt 4: Ereignis in Billomat auslösen |
Das Ereignis manuell auslösen – z.B. eine Rechnung erstellen. → Dabei den Status 'Test' im Hinterkopf behalten |
| Schritt 5: Auf webhook.site nachschauen |
Auf der webhook.site-Seite erscheint nun sofort die Nachricht von Billomat! → Man kann Header und Body der Nachricht genau ansehen → Wenn nichts erscheint → Webhook feuert nicht → Fehlersuche nötig |
|
💡 Dieser Test hilft immer weiter! Mit webhook.site kann man in 2 Minuten prüfen, ob Billomat den Webhook überhaupt sendet. Wenn auf webhook.site nichts ankommt, ist das Problem auf Billomat-Seite (falsch konfiguriert, falsches Ereignis). Wenn etwas ankommt, liegt das Problem im System des Kunden. |
5. Was kann schiefgehen? Fehlersuche!
5.1 Typische Probleme und Lösungen
Problem |
Mögliche Ursache |
Prüfen |
"Der Webhook feuert gar nicht" |
Webhook nicht aktiv / falsch konfiguriert |
Webhook in Billomat prüfen: aktiv? richtiges Ereignis? |
"Daten kommen nicht bei uns an" |
Ziel-URL nicht erreichbar |
Mit webhook.site testen: kommt dort etwas an? |
"Der Webhook wurde deaktiviert" |
Zielsystem hat 4-mal nicht geantwortet |
Account-Inhaber hat E-Mail bekommen; Webhook neu aktivieren nach Behebung des Problems |
"Wir bekommen doppelte Nachrichten" |
Mehrere Ereignisse lösen sich gegenseitig aus |
Prüfen welche Webhooks eingerichtet sind; ggf. reduzieren |
"Wir bekommen zu viele Nachrichten" |
Zu viele Ereignisse abonniert |
Nur die wirklich benötigten Ereignisse abonnieren |
"Die Reihenfolge stimmt nicht" |
Mehrere Ereignisse gleichzeitig ausgelöst |
X-Billomat-Webhook-Request-Id zur Sortierung nutzen |
5.2 Wiederholungsversuche von Billomat (Retry-Logik)
Wenn das Zielsystem nicht mit Status 200 antwortet, versucht Billomat die Nachricht automatisch erneut zu senden:
Versuch |
Wann? |
Was passiert bei Fehler? |
|
Sofort |
Fehler → Versuch 2 |
|
Nach 1 Minute |
Fehler → Versuch 3 |
|
Nach 1 Stunde |
Fehler → Versuch 4 |
|
Nach 6 Stunden |
Fehler → Webhook wird DEAKTIVIERT |
Deaktiviert |
— |
Account-Inhaber bekommt eine E-Mail von Billomat |
|
💡 Sonderfall: HTTP 410 (Gone) Wenn das Zielsystem mit Status 410 antwortet, wird der Webhook sofort und ohne weitere Versuche deaktiviert. Das bedeutet: Die URL existiert bewusst nicht mehr. Kein erneuter Versuch. |
5.3 So erkennst du, ob der Webhook erfolgreich war
Billomat selbst hat kein Log-Interface für Webhooks direkt in der Oberfläche – aber es gibt Wege:
Methode |
Was sie zeigt |
Wie? |
webhook.site |
Ob Billomat überhaupt sendet |
Temporäre URL eintragen, Ereignis auslösen, auf webhook.site nachschauen |
Eigenes System des Kunden |
Ob Daten angekommen sind |
In der Anwendung des Kunden nachschauen |
Account-E-Mail prüfen |
Ob Webhook deaktiviert wurde |
Billomat schickt automatisch eine E-Mail bei Deaktivierung |
X-Billomat-Webhook-Request-Id |
Reihenfolge der Nachrichten prüfen |
Die ID steigt mit jeder Nachricht an |
6. API vs. Webhook – Wann nimmt man was?
Häufige Frage im Support: "Soll ich die API oder einen Webhook nutzen?" – Hier die klare Antwort:
🔁 Nutze die API, wenn... |
🪝 Nutze Webhooks, wenn... |
...du einmalig Daten abrufen möchtest |
...du sofort informiert werden willst, wenn etwas passiert |
...du etwas gezielt erstellen/ändern möchtest |
...ein anderes System automatisch aktualisiert werden soll |
...du nach Daten suchen willst (Filter) |
...du API-Kontingent sparen möchtest |
...du auf Knopfdruck eine Aktion auslösen möchtest |
...du auf Ereignisse reagieren möchtest, ohne ständig zu fragen |
|
💡 Praxisbeispiel: Webshop-Anbindung Ein Kunde hat einen WooCommerce-Shop und Billomat. Wenn eine Bestellung eingeht, soll automatisch eine Rechnung in Billomat erstellt werden (API). Wenn die Rechnung in Billomat als bezahlt markiert wird, soll der Bestellstatus im Shop automatisch auf 'Bezahlt' gesetzt werden (Webhook mit invoice.status-Ereignis). |
Kommentare
0 Kommentare
Zu diesem Beitrag können keine Kommentare hinterlassen werden.