# Webhooks

Sende eine signierte Anfrage an deine eigene URL, sobald ein Shortcut in deinem Workspace erstellt, geändert oder gelöscht wird, damit ein anderes System auf dem Stand bleibt.

> **Wer kann diese Funktion nutzen?**
>
> - **Workspace-Inhaber** und **Admins** können Webhooks verwalten
> - Verfügbar in den [Tarifen Business und Enterprise](https://uselora.com/pricing)

## Überblick

Ein Webhook ist eine HTTPS-URL auf deinem Server. Lora sendet ihr für jedes Ereignis, das du auswählst, eine Anfrage: ein Shortcut wurde erstellt, geändert oder gelöscht. Jede Anfrage ist signiert, damit dein Server prüfen kann, dass sie von Lora kommt. Gesendet werden nur Shortcuts, die alle im Workspace sehen können.

Webhooks gehören dem Workspace, nicht einer einzelnen Person. Jeder Workspace-Inhaber und jeder Admin sieht und verwaltet dieselben Webhooks, und ein Webhook funktioniert weiter, wenn die Person, die ihn erstellt hat, den Workspace verlässt.

Webhooks verwaltest du unter **Einstellungen** und dann **Webhooks**. Die Liste zeigt jeden Webhook mit seinem Namen, einem grünen Punkt und **Aktiviert**, solange er aktiv ist, und seiner URL. Klicke auf einen Webhook, um seine Seite zu öffnen: Status, URL, Signing-Secret, Ereignisse und seine fehlgeschlagenen Zustellungen. Entwickler können Webhooks auch über die [API](https://uselora.dev/essentials/webhooks) verwalten.

## Einrichten

### Webhook erstellen

1. Klicke in deinem Workspace in der Seitenleiste auf **Einstellungen** und dann auf **Webhooks**.
2. Klicke auf **Neuer Webhook**.
3. Gib eine **Bezeichnung** ein, damit du Webhooks unterscheiden kannst.
4. Gib die **URL** ein. Sie muss mit `https://` beginnen und einen öffentlichen Hostnamen verwenden. IP-Adressen und private Netzwerke sind nicht erlaubt, und Lora folgt keinen Weiterleitungen.
5. Kopiere das **Signing-Secret** und speichere es dort, wo dein Server es lesen kann. Lora erzeugt es für dich und speichert es mit dem Webhook.
6. Wähle die Ereignisse, die der Webhook erhält: **Shortcut erstellt**, **Shortcut geändert** und **Shortcut gelöscht**.
7. Klicke auf **Webhook erstellen**.

Lora öffnet die Seite des neuen Webhooks. Das Secret kannst du jederzeit wieder anzeigen (siehe [Signing-Secret anzeigen oder rotieren](#signing-secret-anzeigen-oder-rotieren)).

Ein Workspace kann bis zu 10 Webhooks haben, und jede URL kann nur einmal ein Webhook sein.

> **Hinweis:** Ein Webhook erhält Ereignisse erst ab dem Moment, in dem du ihn erstellst. Für Shortcuts, die sich vorher geändert haben, sendet Lora nichts.

### Prüfen, dass Anfragen von Lora kommen

Dein Server sollte die Signatur jeder Anfrage prüfen. An deine URL kann jeder eine Anfrage schicken, und nur eine mit deinem Secret signierte Anfrage kommt von Lora. Details und Codebeispiele findest du auf der [Webhook-Seite für Entwickler](https://uselora.dev/essentials/webhooks#verify-the-signature).

### Testereignis senden

1. Öffne den Webhook, klicke oben rechts auf das Menü (**…**) und dann auf **Testereignis senden**.
2. Wähle ein Ereignis und klicke auf **Testereignis senden**.

Lora sendet sofort ein Beispielereignis und zeigt, was dein Server geantwortet hat. Ein Test ist ein einziger Versuch: Lora wiederholt ihn nicht, und er zählt nicht dafür, den Webhook zu deaktivieren.

## Grundlagen

### Sehen, was fehlgeschlagen ist

**Fehlgeschlagene Zustellungen** auf der Seite eines Webhooks listet die Zustellungen der letzten 30 Tage auf, die fehlgeschlagen sind, nachdem Lora alle Wiederholungen aufgebraucht hat, die neuesten zuerst. Zugestellte Zustellungen stehen nicht in der Liste, und auch nicht die, die noch auf eine Wiederholung warten. Lora wiederholt eine fehlgeschlagene Zustellung mehrmals innerhalb von etwa einem Tag.

Klicke auf eine Zustellung, um jeden Versuch mit dem Status deines Servers, dem Anfang seiner Antwort und der Dauer zu sehen. Die Details zeigen auch den Anfrage-Body, den Lora gesendet hat. Lora blendet den Body aus, wenn der Shortcut für den Workspace nicht mehr sichtbar ist.

Das Ergebnis eines Testereignisses siehst du sofort im Testdialog. In der Liste steht es nur, wenn es fehlgeschlagen ist.

### Zustellung erneut senden

1. Klicke unter **Fehlgeschlagene Zustellungen** auf die Zustellung.
2. Klicke auf **Erneut senden**.

Lora sendet dasselbe Ereignis noch einmal, mit neuer Signatur. Die Ereignis-ID bleibt gleich, daher kann dein Server ein Duplikat erkennen. Eine Zustellung, die noch auf eine Wiederholung wartet, lässt sich nicht erneut senden. Sende sie erneut, sobald sie beendet ist.

### Signing-Secret anzeigen oder rotieren

- Um das Secret wieder zu sehen, öffne den Webhook und klicke neben **Signing-Secret** auf das Augensymbol. Das Kopiersymbol kopiert es. Lora hält jedes Anzeigen und Kopieren eines Secrets im Audit-Log des Workspace fest.
- Um es zu ersetzen, klicke neben dem Secret auf das Rotieren-Symbol. Das neue Secret signiert sofort jede Anfrage. Das alte signiert noch 24 Stunden mit, damit du deinen Server ohne verlorene Ereignisse umstellen kannst. Wenn du innerhalb dieser 24 Stunden erneut rotierst, ersetzt das neue das ältere Secret.
- Wenn das Secret abgeflossen ist, aktiviere beim Rotieren **Aktuelles Secret sofort stoppen**. Mit dem alten Secret signierte Anfragen lassen sich dann sofort nicht mehr prüfen, stelle deinen Server also zuerst um.

### Webhook ändern, deaktivieren oder löschen

Im Menü (**…**) auf der Seite des Webhooks:

- **Bearbeiten** öffnet eine Seite, auf der du die Bezeichnung, die URL oder die Ereignisse änderst. Wenn du die URL änderst, beginnt der Webhook von vorn: Zustellungen, die noch auf die alte Adresse warten, werden abgebrochen, und der Fehlerverlauf wird zurückgesetzt. Dasselbe gilt für Zustellungen, die auf ein entferntes Ereignis warten. Lora warnt dich, bevor du speicherst.
- **Webhook deaktivieren** stoppt alle Zustellungen an den Webhook und bricht die wartenden ab. **Webhook aktivieren** startet wieder, ohne die Ereignisse, die Lora dazwischen übersprungen hat.
- **Löschen** entfernt den Webhook und bricht ab, was noch auf ihn wartet.

> **Hinweis:** Wenn dein Server mit `410 Gone` antwortet oder fünf Tage lang jede Zustellung fehlschlägt, deaktiviert Lora den Webhook und schickt den Inhabern und Admins des Workspace eine E-Mail. Behebe das Problem auf deinem Server, aktiviere den Webhook und sende ein Testereignis.

## Was die Meldungen bedeuten

Wenn eine Zustellung fehlschlägt, sagt Lora, was du als Nächstes tun kannst. Die Meldung siehst du unter **Fehlgeschlagene Zustellungen** und in den Details der Zustellung.

| Meldung | Was zu tun ist |
| --- | --- |
| Dein Endpunkt hat 401 oder 403 zurückgegeben | Prüfe, ob dein Server Anfragen mit dem aktuellen Signing-Secret verifiziert und Anfragen von Lora annimmt. |
| Dein Endpunkt hat 404 zurückgegeben | Prüfe den URL-Pfad. |
| Dein Endpunkt hat 410 Gone zurückgegeben | Lora hat den Webhook deaktiviert. Aktiviere ihn wieder, sobald dein Server Ereignisse annimmt. |
| Dein Endpunkt hat mit einer Weiterleitung geantwortet | Lora folgt Weiterleitungen nicht. Nutze die endgültige URL. |
| Dein Endpunkt hat 429 zurückgegeben | Erhöhe das Limit auf deinem Server oder antworte schneller. Lora versucht es später erneut. |
| Dein Endpunkt hat einen 5xx-Status zurückgegeben | Dein Server konnte die Anfrage nicht verarbeiten. Prüfe seine Logs. |
| Dein Endpunkt hat nicht innerhalb von 15 s geantwortet | Antworte sofort mit einem 2xx-Status und verarbeite das Ereignis danach. |
| Lora konnte deinen Endpunkt nicht erreichen | Prüfe, ob dein Server online ist und ein gültiges TLS-Zertifikat hat. |
| Das DNS für diesen Host löst auf eine private Adresse auf | Nutze einen Hostnamen, der auf eine öffentliche Adresse auflöst. |
| Der Hostname lässt sich nicht auflösen | Prüfe die URL auf Tippfehler und ob der DNS-Eintrag existiert. |
| Das Signing-Secret des Webhooks ließ sich nicht öffnen | Rotiere das Secret. |

## Wenn sich dein Tarif ändert

Wechselt der Workspace in einen Tarif ohne Webhooks, behält Lora deine Webhooks, sendet aber nichts an sie. **Einstellungen** und dann **Webhooks** bleibt offen, du kannst also die fehlgeschlagenen Zustellungen lesen, Webhooks deaktivieren und löschen. Um Webhooks zu erstellen, zu bearbeiten, zu testen oder zu aktivieren, [wechsle auf Business](https://uselora.com/pricing).

## FAQ

**Ich habe das Signing-Secret verloren.**
Öffne den Webhook und klicke neben **Signing-Secret** auf das Augensymbol. Wenn du lieber neu anfangen möchtest, rotiere es.

**Ein Webhook hat sich selbst deaktiviert.**
Lora deaktiviert einen Webhook, wenn dein Server mit `410 Gone` antwortet oder fünf Tage lang jede Zustellung fehlgeschlagen ist. Die Seite des Webhooks zeigt, welcher Fall es war. Behebe das Problem auf deinem Server, aktiviere den Webhook und prüfe ihn mit einem Testereignis.

**Mein Server bekommt keine Ereignisse für bestehende Shortcuts.**
Webhooks senden nur Änderungen ab jetzt. Für die Vergangenheit sendet Lora keine Ereignisse. Lies deine bestehenden Shortcuts über die API.

**Eine Zustellung zeigt „Nicht gesendet“.**
Der Shortcut war beim Versuch privat, nicht gelistet oder gelöscht, oder der Webhook war deaktiviert. Lora sendet nie den Inhalt eines Shortcuts, den der Workspace nicht sehen kann.

**Ich sehe Webhooks nicht in den Einstellungen.**
Nur Inhaber und Admins sehen es, und erst wenn Webhooks für den Workspace verfügbar sind. Frag einen Inhaber oder Admin.