Webhooks

Ein Webhook meldet einem anderen Programm sofort, wenn in Hausverwalter.ai etwas passiert, zum Beispiel wenn eine Konversation entsteht oder eine Buchung gesetzt wird. Dein Programm muss also nicht ständig nachfragen.

Du findest Webhooks unter „Einstellungen“ › „Webhooks“ und brauchst das Recht „API-Schlüssel und Webhooks“. Alle Ereignisse und Felder stehen in der „API-Dokumentation“ oben auf der Seite.

Webhook anlegen

Klick auf „Webhook anlegen“ und trag die „Ziel-URL“ ein, die mit https beginnen muss und öffentlich erreichbar ist. Unter „Ereignisse“ wählst du aus Gruppen wie „Aufgaben“, „Kontakte“, „Liegenschaften, Einheiten, Verträge“, „Termine“ und „Aufträge“, mit „Alle“ und „Keine“ auch gesammelt. Ist das Modul an, kommt die Gruppe „Buchhaltung“ dazu.

Webhook anlegen

Nach „Anlegen“ steht das „Signatur-Secret“ auf dem Bildschirm. Es wird nur jetzt angezeigt, also speicher es sofort in deinem Programm.

Was bei dir ankommt

Jede Meldung ist ein JSON mit den Feldern id, event, timestamp, occurred_at, entity_id und data. Mit jeder Meldung schickt Hausverwalter.ai diese Header:

  • X-Webhook-Event: das Ereignis.
  • X-Webhook-Id: die eigene ID der Meldung, damit du keine doppelt verarbeitest.
  • X-Webhook-Attempt: der wievielte Versuch das ist.
  • X-Webhook-Signature: HMAC-SHA256 über den Text der Meldung, als Hex.
  • X-Webhook-Timestamp: der Zeitpunkt in Unix-Sekunden.
  • X-Webhook-Timed-Signature: HMAC-SHA256 über Zeitpunkt, Punkt und Text der Meldung.

Berechne die Signatur mit deinem Secret und vergleiche sie, bevor du einer Meldung traust. Die Reihenfolge ist meist richtig, aber eine Wiederholung kann später ankommen.

Wiederholungen und Pausieren

Dein Programm hat 10 Sekunden Zeit und antwortet mit einem Status zwischen 200 und 299. Sonst versucht Hausverwalter.ai es insgesamt 8 Mal, nach 1 und 5 Minuten, 30 Minuten, 2, 6, 12 und 24 Stunden.

Kommt 72 Stunden lang keine erfolgreiche Antwort, pausiert der Webhook. Das passiert auch sofort, wenn deine Adresse mit 410 antwortet. Du bekommst dann eine Nachricht.

Zustellungen prüfen

Ein Klick auf den Webhook zeigt jede Zustellung der letzten 30 Tage mit „Zeit“, „Ereignis“, „Versuche“ und „HTTP“. Der Filter „Fehlgeschlagen“ zeigt nur die Probleme, und mit „Erneut senden“ schickst du eine Meldung noch einmal.

Mit „Test senden“ schickst du Beispieldaten an deine Adresse, gekennzeichnet mit test: true. Beides geht nicht, solange der Webhook pausiert ist. Über „Fortsetzen“ schaltest du ihn wieder ein und kannst dabei die fehlgeschlagenen Meldungen der letzten 30 Tage erneut senden.

Secret erneuern

Im Menü „⋯“ findest du „Secret erneuern“, „Pausieren“ und „Löschen“. Nach dem Erneuern gilt das alte Secret noch 24 Stunden, und im Header stehen beide Signaturen mit Komma getrennt. So stellst du dein Programm ohne Ausfall um.