Webhooks: bei Buchung und Bezahlung benachrichtigen

Ein Webhook ist eine Adresse deines eigenen Programms, die PetWorkers von sich aus aufruft. So erfährt zum Beispiel dein n8n-Ablauf, dein Kassensystem oder deine Auswertung sofort von einer neuen Buchung oder einer bezahlten Rechnung – ohne ständig nachzufragen.

Wann ruft PetWorkers deine Adresse auf?

Es gibt zwei Ereignisse. Für jedes trägst du eine eigene Adresse ein:

• bei Buchung — sobald eine Buchung verbindlich ist. Wartelisten, Anfragen und Entwürfe zählen erst, wenn du sie bestätigt hast.
• bei Bezahlung — sobald die Rechnung zu einer Buchung vollständig bezahlt ist.

Jede Buchung löst jedes Ereignis genau einmal aus. Das gilt für fast alle Buchungsarten: Gruppen, Schnupperstunden, Kurse, FlexKurse, Veranstaltungen, Einzeltermine, Tagesbetreuung, DogWalk, Hausbetreuung, Pension, Pension pro und Platzvermietung. Shop-Bestellungen zählen ab dem Abschluss der Rechnung. Kostenlose Digitalkäufe zählen sofort und lösen beide Ereignisse aus.

Buchungen, die es schon vor dem Einrichten gab, werden nicht nachträglich gemeldet.

So richtest du einen Webhook ein

1. Melde dich als Administrator an.
2. Klicke im Menü auf System → Einstellungen.
3. Klicke oben auf den Knopf Webhooks: Buchung und Bezahlung.

   

4. Trage unter Webhook-URL „bei Buchung“ die Adresse ein, die bei neuen Buchungen aufgerufen werden soll.
5. Trage unter Webhook-URL „bei Bezahlung“ die Adresse für bezahlte Rechnungen ein. Brauchst du ein Ereignis nicht, lass das Feld leer.

   

6. Klicke auf Speichern.

   

Geklappt hat es, wenn oben „Webhook-Adressen gespeichert.“ erscheint. Ab jetzt merkt PetWorkers jede neue Buchung vor und ruft deine Adresse etwa alle fünf Minuten im Hintergrund auf.

So testest du einen Webhook

1. Speichere zuerst die Adresse (siehe oben).
2. Klicke auf Webhook testen: Buchung oder Webhook testen: Bezahlung.

   

3. Lies die Meldung „Test im Protokoll angelegt. Der nächste Hintergrundlauf verarbeitet ihn.“
4. Warte etwa fünf Minuten und lade die Seite neu.
5. Schau im Kasten Letzte Aufrufe in die Spalte Status: „ok“ heißt, dein Programm hat den Aufruf angenommen.

Ein Test ruft deine Adresse mit type=test und id=0 auf. So kann dein Programm Tests von echten Buchungen unterscheiden.

Die Felder im Überblick

• Webhook-URL „bei Buchung“ — die Adresse für neue verbindliche Buchungen. Beispiel: https://hooks.example.com/petworkers/buchung. Leer heißt: abgeschaltet.
• Webhook-URL „bei Bezahlung“ — die Adresse für vollständig bezahlte Rechnungen. Leer heißt: abgeschaltet.
• Speichern — prüft und speichert beide Adressen auf einmal.
• Webhook testen: Buchung und Webhook testen: Bezahlung — legen je einen Testaufruf an.
• Letzte Aufrufe — die letzten 100 Aufrufe mit Erstellt, Ereignis / Buchungsart, Buchung, Status, Versuche / HTTP und Ergebnis (Fehlertext).

Die Zahlen unter der Überschrift zeigen, wie viele Aufrufe noch „vorgemerkt“ sind und wie viele du „zu prüfen“ hast (endgültig fehlgeschlagen oder ungewiss).

Was die Spalte „Status“ bedeutet

• pending — vorgemerkt, wird beim nächsten Hintergrundlauf aufgerufen.
• retry — der Aufruf hat nicht geklappt, PetWorkers versucht es erneut.
• ok — dein Programm hat mit einem Erfolgscode (200–299) geantwortet.
• failed — nach vier Versuchen endgültig fehlgeschlagen. Die Spalte Ergebnis nennt den Grund.
• uncertain — der Hintergrundlauf brach mitten im Aufruf ab. Ob dein Programm ihn bekam, ist unklar. PetWorkers wiederholt ihn bewusst nicht; prüfe in deinem Programm nach.
• simulated — der Mailversand der Instanz ist gesperrt (zum Beispiel in einer Testinstanz). Dann wird nur protokolliert, deine Adresse wird nicht aufgerufen.

Für Fortgeschrittene: so sieht der Aufruf aus

PetWorkers ruft deine Adresse mit GET auf und hängt drei Werte an:

https://hooks.example.com/petworkers/buchung?id=4711&type=course&event=booking

• event — booking oder payment.
• type — die Buchungsart: group, trialguest, course, flexcourse, singleevent, blockevent, seriesevent, coaching, generic, daycare, dogwalk, hourlycare, pension, pensionpro, rentalplace, shop oder digitalproduct (bei Tests test).
• id — die Nummer der Buchung. Bei shop ist es die Nummer der Rechnung bzw. Bestellung, bei digitalproduct die Nummer der Verkaufszeile.

Eigene Werte in deiner Adresse (zum Beispiel ?quelle=petworkers) bleiben erhalten; nur id, type und event werden ersetzt. Die Daten der Buchung selbst schickt der Webhook nicht mit. Dein Programm holt sie bei Bedarf über die Schnittstelle (siehe Daten lesen).

Jeder Aufruf trägt die Kopfzeile Idempotency-Key, zum Beispiel booking:course:4711. Bekommt dein Programm denselben Schlüssel zweimal, soll es den zweiten Aufruf ignorieren.

Weitere Regeln:

• Dein Programm muss innerhalb von zwei Sekunden antworten. Weiterleitungen werden nicht verfolgt.
• Antwortet es nicht mit 200–299 oder ist es nicht erreichbar, versucht PetWorkers es bis zu viermal: nach 5, 10 und 20 Minuten. Danach steht der Aufruf auf „failed“.
• Erlaubt sind nur öffentliche Adressen mit http oder https, ohne Benutzername oder Kennwort in der Adresse und ohne #. Adressen im eigenen Netz (zum Beispiel 192.168.… oder ….local) werden abgelehnt.