# Webhooks einrichten

Webhooks sind **Push-Nachrichten** von SendDrop an eine URL Ihrer Wahl. Statt regelmäßig per API-Poll nach neuen Status zu fragen, bekommen Sie Events direkt zugestellt.

***

### Wann sind Webhooks sinnvoll?

* **Tracking-Updates** in Ihr Shop-/ERP-System übertragen, sobald ein Paket zugestellt ist.
* **Label-Rückmeldungen** (Label erzeugt, storniert) verarbeiten.
* **Rechnungen** automatisch ablegen, sobald fertig.

***

### Webhook einrichten

{% stepper %}
{% step %}

#### Einstellungen → Webhooks

Öffnen Sie in der Sidebar **Einstellungen → Webhooks**.
{% endstep %}

{% step %}

#### „Neuer Webhook"

Klicken Sie auf den Button.
{% endstep %}

{% step %}

#### URL eintragen

Die URL muss:

* per **HTTPS** erreichbar sein,
* ein **2xx-Response** innerhalb 10 s zurückgeben.
  {% endstep %}

{% step %}

#### Events abonnieren

Wählen Sie ein oder mehrere Events:

* `order.created`
* `label.created`
* `tracking.updated`
* `tracking.delivered`
* `label.canceled`
* `invoice.created`
  {% endstep %}

{% step %}

#### Signatur-Secret kopieren

Wird automatisch generiert. Kopieren und sicher speichern.
{% endstep %}

{% step %}

#### Speichern & Testen

Mit „Test senden" erhalten Sie eine Beispiel-Payload zur Validierung.
{% endstep %}
{% endstepper %}

\[BILD-050 – Bild einfügen, welches Folgendes darstellt: Webhook-Konfigurations-Dialog mit URL-Feld, Event-Checkboxen und dem Signatur-Secret mit Kopier-Symbol.]

***

### Payload-Beispiel

```json
{
  "id": "evt_9a8b7c",
  "type": "tracking.delivered",
  "createdAt": "2026-04-18T14:32:11Z",
  "data": {
    "orderId": "ord_abc123",
    "trackingNumber": "123456789012",
    "deliveredAt": "2026-04-18T14:30:02Z",
    "recipientName": "Max Mustermann"
  }
}
```

***

### Signatur verifizieren

Jedes Webhook-Request enthält einen Header:

```
X-SendDrop-Signature: sha256=abcd1234...
```

Berechnen Sie auf Ihrer Seite `HMAC-SHA256(secret, body)` und vergleichen Sie hex-codiert. Beispiel Node.js:

```js
import crypto from "crypto";

function isValid(body, signatureHeader, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}
```

{% hint style="warning" %}
**Prüfen Sie die Signatur bei jedem Request.** Sonst kann jeder mit Ihrer URL gefälschte Events einschleusen.
{% endhint %}

***

### Retry-Verhalten

Antwortet Ihre URL nicht mit **2xx** innerhalb von 10 s, versucht SendDrop es erneut:

| Versuch                  | Abstand   |
| ------------------------ | --------- |
| 1. Retry                 | 30 s      |
| 2. Retry                 | 2 min     |
| 3. Retry                 | 10 min    |
| 4. Retry                 | 1 h       |
| 5. Retry                 | 6 h       |
| Endgültig fehlgeschlagen | nach 24 h |

Nach finaler Fehlschlag wird das Event im Webhook-Log als **„Failed"** markiert und kann manuell erneut versandt werden.

***

### Webhook-Log einsehen

Unter **Einstellungen → Webhooks → \[Webhook öffnen] → Log** sehen Sie:

* **Zeitpunkt**
* **Event-Typ**
* **HTTP-Status Ihrer URL**
* **Versuchszählung**
* **Payload & Antwort** (zum Debuggen)

***

### Best Practices

* **Antworten Sie schnell (2xx)**, und verarbeiten Sie asynchron (z. B. Message-Queue).
* **Idempotent** designen: dasselbe Event kann Sie mehrmals erreichen (Retries), verarbeiten Sie es nur einmal. Nutzen Sie `evt_...` als Key.
* **Fehler-Robustheit**: Ein vorübergehender Fehler (z. B. DB down) führt zum Retry – tolerieren.
* **Separate Endpoint pro Umgebung**: Prod / Staging / Dev – jeweils eigene Webhook-Config.

***

### Siehe auch

{% content-ref url="/pages/ZFJXurN97mu1mgXyHzat" %}
[SendDrop REST-API: Überblick](/10.-entwickler-and-integrationen/rest-api-ueberblick.md)
{% endcontent-ref %}

{% content-ref url="/pages/YMo2pftej5EmimqvdIny" %}
[Rate Limits & Fehlerbehandlung](/10.-entwickler-and-integrationen/rate-limits-fehler.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.senddrop.com/10.-entwickler-and-integrationen/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.