Webhooks einrichten

Mit einem API-Schlüssel holt ein anderes Programm Ihre Daten ab, wenn es sie braucht. Bei einem Webhook ist es umgekehrt: Wir schicken eine Nachricht an eine Adresse von Ihnen, sobald etwas passiert.

Das spart Wartezeit. Eine Bestellung, die um Viertel nach acht hereinkommt, steht um Viertel nach acht in Ihrer Buchhaltung — und nicht bei der nächsten Runde, eine Stunde später.

Wofür Kunden das nutzen:

• jeder Verkauf sofort in der Buchhaltung oder in einer eigenen Datenbank;
• ein kleiner Bildschirm am Eingang, der zeigt, wer gerade hereinkam;
• eine Nachricht in einem Gruppenchat, sobald eine Führung ausverkauft ist;
• eine eigene E-Mail oder SMS an den Käufer, zusätzlich zu unserer.

Dieser Artikel ist die Anleitung zum Bildschirm, Schritt für Schritt. Möchten Sie erst wissen, was ein Webhook ist und ob Sie einen brauchen, lesen Sie Webhooks.

Gut zu wissen: Webhooks gehören zum selben Tarif wie die API. Auf einem kleineren Tarif steht API-Zugang nicht in Ihrem Menü; landen Sie trotzdem auf dem Bildschirm, sehen Sie eine Erklärung und eine Schaltfläche Zum Abonnement.

Wo Sie hinmüssen

Öffnen Sie im linken Menü Einstellungen → API-Zugang und klicken Sie oben auf den Reiter Webhooks. Nur die Rolle Eigentümer sieht diesen Bildschirm.

Sie sehen drei Blöcke: Wir rufen Sie an (Erklärung), Neues Ziel (das Formular) und Ziele (was schon da ist).

Was Sie brauchen

Eine Sache, und die muss schon da sein, bevor Sie anfangen: eine Adresse auf Ihrem eigenen Server, die Nachrichten empfangen kann. Das ist ein Stück Programmierarbeit auf Ihrer Seite — Ihr Webentwickler oder Ihre Buchhaltungssoftware weiß, was Sie meinen, wenn Sie „ein Endpunkt für Webhooks" sagen.

Drei Anforderungen:

1. Es muss https sein. Eine gewöhnliche http-Adresse lehnen wir ab: über diese Leitung gehen Daten von Käufern.
2. Sie muss von außen erreichbar sein. Eine Adresse innerhalb Ihres eigenen Büronetzwerks (etwas mit 192.168. oder 10.) können wir nicht erreichen, und wir lehnen sie ebenfalls ab.
3. Sie muss schnell antworten. Wir warten zehn Sekunden. Dauert die Verarbeitung länger, lassen Sie Ihren Server sofort „ok" sagen und danach weiterarbeiten.

Ein Ziel hinzufügen

Schritt 1. Tragen Sie die Adresse ein. Im ersten Feld (https://...) die vollständige Adresse, an die wir senden dürfen, zum Beispiel https://buchhaltung.meinefirma.de/webhooks/tickets.

Schritt 2. Sagen Sie, wofür sie ist. Das zweite Feld (Wofür ist das?) ist nicht Pflicht, aber praktisch. „Unsere Buchhaltung", „Bildschirm an der Kasse". Haben Sie erst drei, wissen Sie so, welches wozu gehört.

Schritt 3. Wählen Sie aus, worüber wir Sie benachrichtigen dürfen. Die Liste steht unter Worüber sollen wir Sie benachrichtigen?. Das ist die wichtigste Entscheidung. Wählen Sie nur, was Sie wirklich verarbeiten: jede Nachricht, die Sie nicht nutzen, ist Arbeit für Ihren Server und Rauschen in Ihrem Protokoll. Mindestens ein Kästchen muss angehakt sein; ein Ziel ohne Nachrichten bekäme nie etwas.

Nachricht	Wann sie rausgeht
Bestellung erstellt	Eine Bestellung ist entstanden (ein Warenkorb zählt nicht).
Bestellung bezahlt	Das Geld ist da.
Bestellung storniert	Die Bestellung wurde storniert oder ist verfallen.
Bestellung erstattet	Es wurde ganz oder teilweise erstattet.
Ticket erstellt	Ein Ticket wurde ausgegeben.
Ticket gescannt	Am Eingang wurde gescannt — auch bei Ablehnung.
Ticket storniert	Ein Ticket wurde storniert oder erstattet.
Zeitslot ausverkauft	Ein Zeitslot ist voll.
Zeitslot wieder frei	In einem vollen Zeitslot ist wieder Platz.
Gutschein ausgegeben	Ein Gutschein wurde verkauft.
Gutschein eingelöst	Von einem Gutschein wurde abgebucht.
Jahreskarte ausgegeben	Eine Jahreskarte wurde angelegt.
Kassensitzung abgeschlossen	Eine Kassenlade wurde gezählt und geschlossen.
Rechnung ausgestellt	Für einen Käufer wurde eine Rechnung oder Gutschrift erstellt.

Schritt 4 (optional). Testziel. Zeigt die Adresse auf eine Testumgebung, haken Sie Testziel (erhält nur Testereignisse) an. Mehr dazu unter „Ein Testziel“ weiter unten.

Schritt 5. Klicken Sie auf Ziel hinzufügen.

Sie können bis zu zwanzig Ziele haben. Haben Sie schon zwanzig, löschen Sie zuerst eines.

Das Geheimnis sehen Sie nur einmal

Direkt danach erscheint ein Geheimnis: eine lange Zeichenfolge, die mit whsec_ beginnt.

Kopieren Sie es jetzt und geben Sie es an denjenigen weiter, der die Anbindung baut. Laden Sie die Seite neu oder wechseln Sie den Reiter, ist es weg.

Mit diesem Geheimnis signieren wir jede Nachricht an Ihre Adresse. Ihr Server kann damit prüfen, dass die Nachricht wirklich von uns kommt und nicht von jemandem, der Ihre Adresse irgendwo aufgeschnappt hat. Das ist kein Luxus: ohne diese Prüfung ist Ihr Endpunkt eine offene Tür, durch die jeder Bestellungen werfen kann.

Geheimnis verloren? Klicken Sie auf Neues Geheimnis. Sie bekommen sofort ein neues, und das alte funktioniert ab dann nicht mehr — vergessen Sie also nicht, es auch auf der anderen Seite zu ersetzen.

Für denjenigen, der die Anbindung baut, steht im Entwicklerportal genau, wie man diese Signatur nachrechnet, mit Beispielen in PHP, JavaScript und Python. Über die API kann er auch eine signierte Beispielnachricht abrufen, um den eigenen Code zu testen, ohne erst einen Verkauf machen zu müssen.

Testen ohne Verkauf

Klicken Sie neben einem Ziel auf Testnachricht. Wir schicken dann eine einzelne Nachricht der Art test.ping — keine echten Daten, nur ein Signal.

Darunter öffnet sich sofort das Nachrichtenprotokoll, damit Sie sehen, was Ihr Server geantwortet hat. Steht dort Angekommen, funktioniert es. Steht dort ein Fehlercode, wissen Sie, wo Sie suchen müssen. Eine Testnachricht geht auch an ein ausgeschaltetes Ziel.

Das Nachrichtenprotokoll

Klicken Sie neben einem Ziel auf Nachrichten. Sie sehen die letzten fünfzig Nachrichten, und pro Nachricht:

• welcher Art sie war und wann sie rausging;
• was Ihr Server zurückgab (die Zahl ist der http-Status; 200 heißt „ok");
• wie oft wir es versucht haben;
• wie es um sie steht: Angekommen, Unterwegs (wir versuchen es noch) oder Nicht zugestellt.

Ist eine Nachricht nicht angekommen, können Sie sie mit Erneut versuchen noch einmal anbieten. Praktisch, nachdem Sie eine Störung auf Ihrer Seite behoben haben.

Nachrichten bleiben dreißig Tage stehen. Danach werden sie aufgeräumt: das Protokoll ist zum Finden eines Problems da, nicht als Archiv.

Was passiert, wenn Ihr Server gerade nicht läuft

Wir geben nicht sofort auf. Kommt eine Nachricht nicht an, versuchen wir es sechsmal erneut, mit immer längeren Abständen: nach einer Minute, fünf Minuten, einer halben Stunde, zwei Stunden, zwölf Stunden und einem Tag. Zusammen gut anderthalb Tage.

Klappt es dann immer noch nicht:

• bekommt das Ziel die Markierung Kommt nicht an;
• erhalten Sie eine E-Mail. Sie geht an die Kontakt-E-Mail Ihrer Organisation oder, wenn diese leer ist, an die Rechnungsadresse (E-Mail) (beide unter Einstellungen → Organisation, Reiter Kontakt);
• bleibt das Ziel eingeschaltet. Spätere Ereignisse werden erneut angeboten, und sobald wieder etwas ankommt, verschwindet die Markierung.

Sie bekommen höchstens eine solche E-Mail pro Tag und Ziel. Ein Server, der ein Wochenende lang ausfällt, erzeugt also keine hundert E-Mails.

Ein Testziel

Wählen Sie beim Anlegen Testziel, wenn die Adresse auf eine Testumgebung zeigt. Ein solches Ziel erhält nur Testereignisse — was mit den Testbestellungen eines Testschlüssels geschieht — und nie echte Verkäufe. Es trägt in der Liste den Vermerk Test. Umgekehrt erhält ein gewöhnliches Ziel nie etwas von einer Testbestellung.

Diese Trennung ist streng, und das mit Absicht: ein Testserver, der versehentlich eine echte Bestellung verarbeitet, schickt eine Bestätigung an einen echten Käufer.

Ausschalten oder löschen

Ausschalten stoppt die Zustellungen, lässt das Ziel aber stehen, mit seinem Geheimnis und seinem Protokoll; es trägt dann den Vermerk Aus. Praktisch während einer Wartung auf Ihrer Seite. Klicken Sie erneut auf Einschalten und es läuft wieder.

Löschen entfernt das Ziel und sein Protokoll. Das lässt sich nicht rückgängig machen; ein neues Ziel bekommt ein neues Geheimnis.

Es gibt einen dritten Fall: antwortet Ihr Server einmal mit dem Code 410, schalten wir das Ziel selbst aus. Dieser Code heißt wörtlich „diese Adresse existiert nicht mehr", und weiter anzuklopfen wäre unhöflich. Dasselbe geschieht, wenn die Adresse inzwischen in ein internes Netz zeigt. Klicken Sie auf Einschalten, sobald es wieder in Ordnung ist.

Drei Tipps für denjenigen, der die Anbindung baut

1. Erst antworten, dann verarbeiten. Sagen Sie sofort „ok" und erledigen Sie die eigentliche Arbeit im Hintergrund. Sonst laufen Sie in unsere zehn Sekunden.
2. Verarbeiten Sie idempotent. Jede Nachricht trägt eine eigene Nummer (den Idempotency-Key). Kommt dieselbe Nummer zweimal an, tun Sie nichts. Wir versuchen es im Zweifel erneut, und eine doppelte Buchung ist schlimmer als eine doppelte Protokollzeile.
3. Verlassen Sie sich nicht auf die Reihenfolge. Zwei Nachrichten können einander überholen, wenn die erste wiederholt wird. Schauen Sie auf die Zeit in der Nachricht und auf ihren Inhalt, nicht auf die Reihenfolge des Eintreffens.

Weiterlesen

• Webhooks — was ein Webhook ist und wann Sie einen brauchen, ohne Fachbegriffe.
• Einen API-Schlüssel anlegen — der andere Reiter dieses Bildschirms.
• Das Entwicklerportal — für den, der die Anbindung baut.