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.

Screenshot 2026-02-19 102029.png

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 (nach 1 Minute, 1 Stunde, 6 Stunden) → 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 → z.B. https://mein-crm.de/webhook/billomat
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?
Versuch	Sofort	Fehler → Versuch 2
Versuch	Nach 1 Minute	Fehler → Versuch 3
Versuch	Nach 1 Stunde	Fehler → Versuch 4
Versuch	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).

Verknüpfung mit