# Webhooks

> Echtzeit-Benachrichtigungen an externe Systeme senden



## Übersicht [#übersicht]

<Frame>
  <img src="/images/webhooks/stamp-webhooks-overview.png" />
</Frame>

Webhooks ermöglichen es, externe Systeme in Echtzeit über Ereignisse in Stampfactory zu informieren. Bei bestimmten Aktionen (z.B. Stempelung, Abwesenheitsantrag) wird automatisch eine HTTP-Anfrage an eine von Ihnen definierte URL gesendet.

## Webhook erstellen [#webhook-erstellen]

<Frame>
  <img src="/images/webhooks/stamp-webhooks-create.png" />
</Frame>

<Steps>
  <Step title="Neuen Webhook anlegen">
    Navigieren Sie zu **Einstellungen > Webhooks** und klicken Sie auf **Neuer Webhook**.
  </Step>

  <Step title="URL eingeben">
    Geben Sie die Ziel-URL ein, an die Ereignisse gesendet werden sollen.
  </Step>

  <Step title="Ereignisse wählen">
    Wählen Sie die Ereignisse, bei denen der Webhook ausgelöst werden soll.
  </Step>

  <Step title="Speichern">
    Der Webhook wird sofort aktiviert.
  </Step>
</Steps>

## Sicherheit [#sicherheit]

Alle Webhook-Anfragen werden mit **HMAC-SHA256** signiert. Der Signaturwert wird im Header `X-Stamp-Signature` mitgesendet. Zusätzlich enthält jede Anfrage eine eindeutige Request-ID im Header `X-Stamp-Request-Id`.

### Signatur verifizieren [#signatur-verifizieren]

```bash
# Beispiel: Signatur mit dem Webhook-Secret verifizieren
echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET"
```

<Warning>
  Verifizieren Sie immer die Signatur, um sicherzustellen, dass die Anfrage tatsächlich von Stampfactory stammt.
</Warning>

## Zustellungsprotokoll [#zustellungsprotokoll]

Jede Webhook-Zustellung wird protokolliert:

| Feld            | Beschreibung                               |
| --------------- | ------------------------------------------ |
| **Zeitpunkt**   | Wann die Zustellung ausgelöst wurde        |
| **Ereignis**    | Welches Ereignis den Webhook ausgelöst hat |
| **Status**      | HTTP-Statuscode der Antwort                |
| **Antwortzeit** | Dauer bis zur Antwort des Zielsystems      |

### Wiederholung [#wiederholung]

Fehlgeschlagene Zustellungen (HTTP-Status >= 400 oder Timeout) werden automatisch wiederholt. Nach mehreren Fehlversuchen wird der Webhook deaktiviert und Sie erhalten eine Benachrichtigung.

## Webhook deaktivieren / löschen [#webhook-deaktivieren--löschen]

Webhooks können jederzeit deaktiviert oder gelöscht werden. Das Zustellungsprotokoll bleibt auch nach dem Löschen erhalten.