Schritt für Schritt
Schnittstellen öffnen
Öffne Einstellungen und wechsle zum Reiter „Schnittstellen“. Dort findest du die Karte „Webhooks“. Hast du den Tarif Free, zeigt BilanQo stattdessen den Hinweis, dass Webhooks im Tarif Pro enthalten sind, und führt dich zum Tarifvergleich.
Webhook anlegen
Mit „Webhook anlegen“ öffnet sich der Dialog. Trage die Ziel-URL deines Programms ein. Erlaubt sind nur Adressen mit https. Interne, lokale und Link-Local-Adressen sind gesperrt, das gilt auch, wenn ein Name erst über das DNS auf eine solche Adresse zeigt.
Ereignisse auswählen
Hake an, wann BilanQo deine URL aufrufen soll: bei „Rechnung erstellt“, „Rechnung versendet“, „Rechnung bezahlt“, „Rechnung storniert“ oder „Kunde angelegt“. Du bekommst nur Aufrufe zu den Ereignissen, die du ausgewählt hast. Mindestens ein Ereignis ist nötig.
Signaturgeheimnis sichern
Nach dem Anlegen zeigt BilanQo das Signaturgeheimnis genau einmal an. Kopiere es und lege es in deinem Programm als geheime Einstellung ab. Danach lässt es sich nicht mehr anzeigen. Ist es verloren, legst du den Webhook neu an.
Signatur prüfen
Jeder Aufruf ist ein POST mit JSON-Inhalt. Im Kopfbereich steht „X-Bilanqo-Signature“ im Format „sha256=“ plus Prüfsumme. Berechne dieselbe HMAC-SHA256-Prüfsumme über den unveränderten Inhalt mit deinem Geheimnis und vergleiche beide Werte.
Testen und Zustellungen ansehen
Mit „Testen“ schickst du einen Testaufruf an deine URL, damit du die Signaturprüfung ausprobieren kannst. Unter dem Webhook listet BilanQo die letzten Zustellungen mit Ereignis, Status, Zeit und Antwortcode.
Wofür ein Webhook gut ist
Ohne Webhook müsstest du in deinem Programm regelmäßig nachfragen, ob sich etwas geändert hat. Mit einem Webhook dreht sich das um: BilanQo ruft deine Adresse auf, sobald das Ereignis eintritt. Das spart Abgleiche und Handarbeit, etwa wenn eine bezahlte Rechnung in einem anderen System abgehakt werden soll.
Der Aufruf enthält den Namen des Ereignisses, einen Zeitstempel und die wichtigsten Daten, bei einer Rechnung zum Beispiel Rechnungsnummer, Status, Gesamtbetrag, Währung und Kunde. Den Aufruf verarbeitet BilanQo im Hintergrund, ein langsamer Empfänger bremst das Erstellen deiner Rechnungen also nicht aus.
Praxis-Tipps für die Signaturprüfung
Prüfe die Signatur immer über den Inhalt genau so, wie er angekommen ist, bevor du ihn als JSON einliest. Schon ein geändertes Leerzeichen ergibt eine andere Prüfsumme. Vergleiche die Werte am besten mit einer Funktion für konstante Laufzeit, die deine Programmiersprache dafür bereitstellt.
Der Kopfbereich enthält außerdem „X-Bilanqo-Event“ mit dem Ereignisnamen und „X-Bilanqo-Delivery“ mit einer eindeutigen Kennung je Zustellung. Mit der Kennung erkennst du doppelte Aufrufe und verarbeitest dasselbe Ereignis nur einmal.
Antworte schnell mit einem 2xx-Code und erledige längere Arbeit danach. Dann gilt die Zustellung als erfolgreich.
Wenn dein Empfänger nicht antwortet
Antwortet dein Programm nicht mit einem 2xx-Code, wiederholt BilanQo den Aufruf mit wachsendem Abstand, nach einer Minute, fünf Minuten, dreißig Minuten, zwei und sechs Stunden. Insgesamt gibt es höchstens fünf Versuche. Danach steht die Zustellung in der Liste als „Aufgegeben“.
Ein kurzer Ausfall deines Programms ist damit meist unproblematisch. Bei längeren Ausfällen gleichst du die verpassten Ereignisse in deinem Programm ab.
Das Anlegen, Ändern, Löschen und Testen von Webhooks wird im Audit-Log festgehalten, und beim Löschen eines Webhooks entfernt BilanQo auch die Zustellprotokolle.
Stand: November 2026. Rechtliche Angaben ersetzen keine Steuer- oder Rechtsberatung; im Einzelfall hilft deine Steuerberatung.