Webhooks ermöglichen deiner Anwendung, umgehend über Ereignisse informiert zu werden, die in deinem Buchungssystem stattfinden. Statt regelmäßig unsere API nach neuen Daten zu fragen, sendet anny automatisch und in Echtzeit relevante Informationen direkt an deine Anwendung. Deine Integrationen sind dadurch effizienter und reagieren blitzschnell.

Was sind Webhooks?

Webhooks sind HTTP-basierte Rückmeldungen ("Callbacks"), die von anny automatisch an deine Anwendung versendet werden, sobald festgelegte Ereignisse eintreten. Stell dir Webhooks als „umgedrehte API-Abfragen“ vor – denn anstelle, dass deine Anwendung ständig bei uns nach Aktualisierungen fragt, informieren wir deine App proaktiv darüber, wenn etwas Wichtiges passiert.

Webhook einrichten

Um einen Webhook einzurichten:

Navigiere über deinen Avatar im anny Admin-Bereich zu den Account Einstellungen und öffne den Reiter API.
Klicke auf + Webhook erstellen.
Trage folgende Details ein:
- Name: Eine aussagekräftige Beschreibung (z.B. „CRM Integration“).
- URL: Die Adresse des Serverendpunkts, an die wir Ereignis-Benachrichtigungen versenden sollen.
- Ereignisse: Wähle ein oder mehrere Ereignisse aus, über die du benachrichtigt werden willst.

Beispiel Konfiguration

{
  "name": "My CRM Integration",
  "url": "https://api.myapp.com/webhooks/bookings",
  "events": ["bookings.created", "bookings.updated"]
}

Verfügbare Events

anny unterstützt Webhooks zu Ereignissen in vier Kategorien:

Buchungs-Ereignisse

Ereignis	Beschreibung
bookings.created	Neue Buchung erstellt
bookings.updated	Buchungsdetails geändert
bookings.started	Buchung hat begonnen
bookings.ended	Buchung wurde abgeschlossen
bookings.checked-in	Kunde hat eingecheckt
bookings.checked-out	Kunde hat ausgecheckt
bookings.deleted	Buchung wurde gelöscht/storniert

Bestell-Ereignisse

Ereignis	Beschreibung
orders.created	Neue Bestellung vorgenommen
orders.updated	Bestellung aktualisiert
orders.deleted	Bestellung storniert/gelöscht

Rechnungs-Ereignisse

Ereignis	Beschreibung
invoices.created	Rechnung generiert
invoices.finalised	Rechnung finalisiert
invoices.updated	Rechnung geändert
invoices.deleted	Rechnung gelöscht oder zurückgenommen

Kunden-Ereignisse

Ereignis	Beschreibung
customers.created	Neuer Kunde registriert
customers.updated	Kundenprofil aktualisiert
customers.deleted	Kundenkonto gelöscht

Einschränkungen nach Kontext (Event Filtering)

Optional – nur bei Buchungs-Ereignissen verfügbar

Durch Kontext-Einschränkungen kannst du festlegen, dass du nur bei Ereignissen zu bestimmten Ressourcen, Kategorien oder Services benachrichtigt wirst:

Wähle zunächst Buchungs-Ereignisse aus.
Aktiviere Mit Einschränkungen innerhalb der Ereignisgruppe
Wähle den gewünschten Filtertyp aus:
- Ressourcen (z.B. bestimmte Räume, Geräte)
- Ressourcengruppen
- Ressourcenkategorien
- Services
- Service-Gruppen

Typische Beispiele:

Benachrichtigungen nur zu Spa-Services („Service-Gruppe: Spa-Services“).
Nur bestimmte Meeting-Räume als Ressourcen auswählen.
Nur Online-Buchungen durch „Service-Gruppe: Online-Buchung“.

Webhook Datenstruktur und Payload

Jeder Webhook enthält strukturierte Informationen zum Ereignis:

{
  "event": "bookings.created",
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "webhook_id": "01H8EXAMPLE123",
  "triggered_at": "2024-01-15T14:30:00Z",
  "data": {
    "id": "1764",
    "code": "!TIXWaEKmLAW8JN8bjRf",
    "type": "bookings",
    "number": "BB533155102",
    "status": "accepted",
    "total": 0,
    "currency": "EUR",
    "service": {
      "id": "1",
      "name": "Tages-Buchung",
      "type": "services",
      "price": 0,
      "currency": "EUR"
    },
    "customer": {
      "id": "2fa9ab69-abd5-45ec-9927-c4894fbf60a2",
      "uuid": "2fa9ab69-abd5-45ec-9927-c4894fbf60a2",
      "email": "00ufvv@ptct.net",
      "full_name": "John Keats",
      "given_name": "John",
      "family_name": "Keats"
    },
    "resource": {
      "id": "18",
      "name": "Schreibtisch 4",
      "type": "resources",
      "timezone": "Europe/Berlin"
    },
    "start_date": "2025-06-13T07:00:00+00:00",
    "end_date": "2025-06-13T16:00:00+00:00",
    "created_at": "2025-06-07T12:54:38+00:00",
    "description": "John Keats"
  }
}

Wichtige Felder

Feld	Beschreibung
event	Art des ausgelösten Ereignisses
event_id	Eindeutige ID dieser Webhook-Auslieferung
webhook_id	ID deines Webhook-Abonnements
triggered_at	Zeitpunkt, an dem das Ereignis passiert ist
data	Vollständige Daten des Elements, das den Webhook auslöst

Sicherheit

Webhook-Signaturen

Webhook-Signaturen sind standardmäßig aktiviert. Die Signatur wird im HTTP-Header „Signature" übermittelt und kann optional zur Verifizierung eingehender Meldungen als authentische anny Requests verwendet werden.

Troubleshooting

Webhook-Auslieferungsverlauf (Call History)

Überwache alle Webhook-Auslieferungen in Echtzeit bequem über die Webhook-Verwaltungsoberfläche. Folgende Status können bei Webhook-Auslieferungen auftreten:

Status	Bedeutung	Erklärung
✅	Erfolg (200-299)	Der Webhook wurde erfolgreich zugestellt.
❌	Fehlgeschlagen (400+)	Zustellung fehlgeschlagen – prüfe die Antwortdetails deines Servers.
⏳	Wartend	Webhook ist in der Warteschlange und wird bald ausgeliefert.
🔄	Neuversuch	Manueller Neuversuch eines fehlgeschlagenen Webhooks.

Details zu Anfrage und Antwort einsehen (Request/Response)

Klicke im Webhook-Auslieferungsverlauf auf eine einzelne Webhook-Auslieferung, um folgende Informationen zu sehen:

Vollständige gesendete Anfrage (Payload)
Antwort deines Servers
HTTP-Statuscode
Anzahl der Zustellversuche

Umgang mit fehlgeschlagenen Webhooks (Retry-Funktionalität)

Automatische Neuversuche

Fehlgeschlagene Webhook-Auslieferungen werden bis zu 3-mal automatisch erneut versucht. Dabei wird die Wartezeit zwischen den Versuchen jedes Mal etwas erhöht (exponentieller Backoff).

Manuelle Neuversuche

Zusätzlich kannst du fehlgeschlagene Webhooks einmal manuell erneut senden:

Öffne die Seite Webhooks → Auslieferungsverlauf.
Suche die fehlgeschlagene Webhook-Zustellung.
Klicke auf die Schaltfläche Erneut senden (Retry). Je Webhook-Auslieferung ist dies nur einmal möglich.
Überwache den neuen Zustellversuch in Echtzeit.

Verwaltung bestehender Webhook-Abonnements

Webhooks aktivieren/deaktivieren

Webhook-Abonnements können jederzeit ein- und ausgeschaltet werden, ohne dass die Konfiguration verloren geht.

Automatische Deaktivierung nach wiederholten Fehlern

Um unnötige Belastungen zu vermeiden und deinen Server zu schützen, deaktiviert anny Webhooks automatisch, wenn 5-mal hintereinander keine erfolgreiche Auslieferung möglich war.

Die Anzahl aufeinanderfolgender Fehler wird dabei im Attribut failure_count deines Webhook-Abonnements gespeichert.

Häufige Integrationsmuster (Integration Patterns)

CRM-Kunden-Synchronisierung

{
  "name": "CRM Kundensynchronisierung",
  "url": "https://api.meincrm.de/webhooks/kunden",
  "events": ["customers.created", "customers.updated"]
}

Buchungs-Benachrichtigungen (z.B. SMS-Alerts)

{
  "name": "SMS Booking Alerts",
  "url": "https://api.smsservice.com/webhooks/bookings",
  "events": ["bookings.created", "bookings.updated", "bookings.checked-in"],
  "restrictions": [
    {
      "type": "services",
      "id": "high-value-services-group"
    }
  ]
}

Analytics-Integration

{
  "name": "Analytics-Tracking",
  "url": "https://analytics.meineapp.de/webhooks/ereignisse",
  "events": ["bookings.created", "bookings.ended", "invoices.finalised"]
}

Fehlerbehebung (Troubleshooting)

Webhook empfängt keine Ereignisse

Stelle sicher, dass das Webhook-Abonnement aktiv ist.
Überprüfe, ob die angegebene URL öffentlich erreichbar ist.
Prüfe, ob dein Server bei erfolgreicher Verarbeitung einen HTTP-Statuscode im Bereich 200 zurück liefert.
Prüfe, ob Kontext-Einschränkungen zu streng gesetzt sind (ggf. anpassen oder entfernen).

Hohe Anzahl an Fehlern („High Failure Count“)

Prüfe die URL deines Endpunkts auf Korrektheit.
Schaue in die Logs deines Servers, um mögliche Fehlerquellen zu identifizieren.

Ereignisse doppelt erhalten („Duplicate Events“)

Verwende die event_id, um doppelte Auslieferungen zu erkennen und sicherzustellen, dass dein System nur einmal darauf reagiert („Idempotenz“).
Prüfe, ob du eventuell doppelte Webhook-Abonnements hast.
Implementiere technische Einschränkungen (z.B. Datenbank-Unique Constraints), um ein doppeltes Verarbeiten der Ereignisse zu vermeiden.

Support bei Webhooks

Falls du bei der Einrichtung oder Nutzung deiner Webhooks Unterstützung benötigst:

Prüfe zunächst den Webhook-Auslieferungsverlauf für Fehlerdetails.
Prüfe deine eigenen Serverlogs für die Webhook-Endpunkte.
Kontaktiere unseren Support mit folgenden Informationen:
- Webhook-Abonnement-ID
- Genaue Fehlermeldungen/Problembeschreibung
- Zeitpunkt, seit dem die Probleme auftreten