Zum Hauptinhalt springen
Hilfe · Abrechnen

Webhooks einrichten und Aufrufe prüfen

Ein Webhook meldet Ereignisse aus BilanQo automatisch an dein eigenes Programm, zum Beispiel an ein Tool für die Buchhaltung, eine Automatisierung oder einen Shop. Du richtest ihn in den Einstellungen unter Schnittstellen ein. Die Funktion ist im Tarif Pro enthalten.

Aufnahme aus der echten Anwendung mit einem Demo-Betrieb · 1:22 Min., mit Ton

Schritt für Schritt

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

Häufige Fragen

Antworten für eine klare Entscheidung

Was ist ein Webhook?

Ein Webhook ist ein automatischer Aufruf einer Internetadresse, sobald in einer Software etwas passiert. In BilanQo ruft die Software deine URL auf, wenn zum Beispiel eine Rechnung bezahlt wird, und schickt die Daten dazu mit.

Welche Ereignisse kann ein Webhook in BilanQo melden?

Rechnung erstellt, Rechnung versendet, Rechnung bezahlt, Rechnung storniert und Kunde angelegt. Für den Testaufruf gibt es zusätzlich ein eigenes Testereignis. Du wählst pro Webhook, welche Ereignisse er bekommt.

Brauche ich dafür den Tarif Pro?

Ja, Webhooks sind eine Funktion im Tarif Pro. Im Tarif Free zeigt BilanQo auf der Seite Schnittstellen einen Hinweis und den Weg zum Tarifvergleich. Aktuelle Preise findest du auf der Seite Preise.

Wie prüfe ich, ob ein Webhook wirklich von BilanQo kommt?

Über die Signatur. BilanQo signiert den Inhalt mit HMAC-SHA256 und deinem Signaturgeheimnis und schickt das Ergebnis im Kopfbereich „X-Bilanqo-Signature“. Rechnest du denselben Wert nach und er stimmt überein, stammt der Aufruf von BilanQo.

Warum wird meine URL abgelehnt?

Die Adresse muss mit https beginnen und von außen erreichbar sein. Interne Adressen, lokale Rechner und Link-Local-Adressen sind aus Sicherheitsgründen gesperrt. Prüfe auch auf Tippfehler im Domainnamen.

Was passiert, wenn mein Server nicht antwortet?

BilanQo wiederholt den Aufruf bis zu fünfmal mit wachsendem Abstand. Bleibt jede Antwort ohne 2xx-Code, erscheint die Zustellung in der Liste als „Aufgegeben“.

Seitenaufrufe und Klicks

Seitenaufrufe zählen wir ohne Cookies auf unserem eigenen Server: welche Seite, woher der Besuch kommt und aus welcher Region (Land und Ort, aus der IP-Adresse abgeleitet). Die IP-Adresse speichern wir für die Statistik nicht im Klartext; sie wird nur verwendet, um Land und Ort zu bestimmen. Server-Logs mit IP-Adressen löschen wir nach 14 Tagen. Mit „Erlauben“ messen wir zusätzlich Klicks und Nutzung, um die Seite zu verbessern. „Ablehnen“ lässt diese Klicks aus. Die Seite funktioniert so oder so. Mehr dazu in der Datenschutzerklärung.