Webhooks

Webhooks ermoeglichen es Ihnen, Echtzeit-Benachrichtigungen zu erhalten, wenn Ereignisse in Ihrem LabelGrid-Konto auftreten. Verwenden Sie Webhooks, um Workflows zu automatisieren und mit externen Systemen zu integrieren.

Fuer Entwickler: Sie koennen Webhooks auch programmatisch ueber die API verwalten. Siehe die LabelGrid API-Dokumentation fuer Endpunkte und Beispiele.

Wie Webhooks funktionieren

Sie konfigurieren einen Webhook - Geben Sie eine URL und die zu ueberwachenden Ereignisse an
Ein Ereignis tritt ein - Zum Beispiel wird ein Release an einen Store geliefert
LabelGrid sendet einen POST-Request - Ihr Server empfaengt die Ereignisdaten
Ihr System verarbeitet es - Automatisieren Sie Workflows basierend auf dem Ereignis

Auf Webhooks zugreifen

Klicken Sie auf Ihr Profilsymbol oben rechts
Waehlen Sie Webhooks aus dem Dropdown-Menue

Einen Webhook erstellen

Klicken Sie auf Create Webhook
Geben Sie einen Name ein, um diesen Webhook zu identifizieren
Geben Sie die URL ein, an die Sie Benachrichtigungen erhalten moechten
Waehlen Sie, welche Events diesen Webhook ausloesen sollen
Klicken Sie auf Create

Webhook Secret

Wenn Sie einen Webhook erstellen, erhalten Sie einen Secret Key. Verwenden Sie diesen, um zu ueberpruefen, ob eingehende Anfragen tatsaechlich von LabelGrid stammen:

Speichern Sie das Secret sicher
Ueberpruefen Sie die Signatur eingehender Anfragen
Falls kompromittiert, generieren Sie das Secret neu

Verfuegbare Ereignisse

Konfigurieren Sie Ihren Webhook fuer diese Ereignisse. Der Ereignis-Identifier ist der Wert, den Sie in der event-Eigenschaft des Payloads und im X-Webhook-Event-Header sehen werden:

Ereignis-Identifier	Beschreibung
`delivery.completed`	Ausgeloest, wenn ein Release erfolgreich an einen Store geliefert wurde
`delivery.failed`	Ausgeloest, wenn die Lieferung an einen Store fehlschlaegt
`takedown.completed`	Ausgeloest, wenn ein Takedown-Request abgeschlossen ist
`release.review.status_changed`	Ausgeloest, wenn sich der Review-Status eines Releases aendert
`release.preflight.report_ready`	Ausgeloest, wenn der Preflight-QC-Bericht fuer ein zurueckgehaltenes Release zum Abruf bereit ist
`stream_radar.flag_created`	Ausgeloest, wenn eine Stream-Radar-Meldung erstellt wird oder eine aufgeloeste Meldung bei einer neuen Erkennung erneut geoeffnet wird
`stream_radar.flag_resolved`	Ausgeloest, wenn eine Stream-Radar-Meldung aufgeloest wird, weil die Erkennungen aufgehoert haben
`release.distributed`	Ausgeloest, wenn ein Release verteilt wird
`payment.statement_ready`	Ausgeloest, wenn eine Zahlungsabrechnung zur Ansicht bereit ist
`transcode.completed`	Ausgeloest, wenn das Audio-Transcoding eines Tracks erfolgreich abgeschlossen wird
`transcode.failed`	Ausgeloest, wenn das Transcoding eines Tracks fehlschlaegt oder unvollstaendig endet
`distribution.outlet.status_changed`	Ausgeloest bei jedem Statuswechsel des Vertriebs pro Outlet

Sie koennen mehrere Ereignisse fuer einen einzelnen Webhook auswaehlen oder separate Webhooks fuer verschiedene Ereignistypen erstellen.

Sie koennen diese Liste auch programmatisch abrufen: GET /api/public/webhooks/event-types gibt jedes Ereignis zusammen mit einem data-Schema zurueck, das dessen Payload-Schluessel und -Typen beschreibt, sodass Consumer mit striktem Schema ihre eingehende Validierung vorab erweitern koennen.

Webhooks verwalten

Ihre Webhooks anzeigen

Die Webhook-Liste zeigt:

Spalte	Beschreibung
Name	Der von Ihnen zugewiesene Webhook-Name
URL	Wohin Benachrichtigungen gesendet werden
Events	Anzahl der konfigurierten Ereignisse
Status	Active oder Inactive
Success / Fail	Anzahl erfolgreicher und fehlgeschlagener Zustellungen
Last Triggered	Wann der Webhook zuletzt aufgerufen wurde

Einen Webhook bearbeiten

Klicken Sie auf die Aktion Edit in der Webhook-Zeile
Aendern Sie Name, URL oder Ereignisse
Klicken Sie auf Save

Aktivieren / Deaktivieren

Schalten Sie den aktiven Status eines Webhooks um, ohne ihn zu loeschen:

Active - Webhook empfaengt Benachrichtigungen
Inactive - Webhook ist pausiert, keine Benachrichtigungen werden gesendet

Einen Webhook loeschen

Klicken Sie auf die Aktion Delete in der Webhook-Zeile
Bestaetigen Sie die Loeschung

Webhooks testen

Bevor Sie sich in der Produktion auf einen Webhook verlassen, testen Sie ihn:

Klicken Sie auf die Aktion Test bei Ihrem Webhook
LabelGrid sendet einen Test-Payload an Ihre URL
Ueberpruefen Sie, ob Ihr Endpunkt ihn korrekt empfangen und verarbeitet hat

Webhook-Logs anzeigen

Ueberwachen Sie Webhook-Aktivitaeten und beheben Sie Probleme:

Klicken Sie auf die Aktion View Logs bei einem Webhook
Sehen Sie den Verlauf aller Webhook-Zustellungen

Log-Details

Jeder Log-Eintrag zeigt:

Feld	Beschreibung
Event Type	Welches Ereignis diese Zustellung ausgeloest hat
Response Status	HTTP-Statuscode von Ihrem Server
Duration	Wie lange die Anfrage gedauert hat
Attempt	Wiederholungsversuch-Nummer
Timestamp	Wann die Zustellung erfolgte

Webhook-Payload-Format

Wenn ein Ereignis eintritt, sendet LabelGrid einen POST-Request an Ihre URL mit einem JSON-Payload:

{
  "event": "delivery.completed",
  "timestamp": "2026-05-05T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    // Ereignisspezifische Daten
  }
}

Das Feld timestamp verwendet das ISO-8601-Format. webhook_id ist die ID Ihres konfigurierten Webhooks (sie entspricht dem X-Webhook-Id-Header).

Event-Payloads

Die Struktur des data-Objekts haengt vom event-Typ ab. Alle Feldtypen unten sind JSON-Typen, wie sie im Payload serialisiert werden.

`delivery.completed`

Wird einmal pro Outlet ausgeloest, wenn eine Release-Zustellung einen finalen Erfolgszustand erreicht.

{
  "event": "delivery.completed",
  "timestamp": "2026-05-18T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "distro_queue_id": 456,
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "outlet_id": 12,
    "outlet_name": "Spotify",
    "status": "complete"
  }
}

Feld	Typ	Beschreibung
`distro_queue_id`	integer	Interne Queue-ID fuer diesen Zustellversuch
`release_id`	integer	Die Release, die zugestellt wurde
`label_id`	integer	Das besitzende Label der Release, sodass Sie das Ereignis ohne zusaetzlichen Lookup weiterleiten koennen
`release_cat`	string \| null	Ihre Release-Katalog-Referenz
`outlet_id`	integer \| null	Die Outlet-Ziel-ID
`outlet_name`	string \| null	Lesbarer Outlet-Name (z. B. `"Spotify"`)
`status`	string	Immer `"complete"` fuer dieses Ereignis

`delivery.failed`

Wird einmal pro Outlet ausgeloest, wenn eine Release-Zustellung einen finalen Fehlerzustand erreicht. Gleicher Payload wie delivery.completed plus ein message-Feld.

{
  "event": "delivery.failed",
  "timestamp": "2026-05-18T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "distro_queue_id": 456,
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "outlet_id": 12,
    "outlet_name": "Spotify",
    "status": "error",
    "message": "Outlet rejected the delivery: missing ISRC."
  }
}

Feld	Typ	Beschreibung
`status`	string	Einer von `error`, `fault`, `rejected`, `batch_exception`
`message`	string \| null	Fehlergrund vom Outlet oder von der Distributions-Pipeline

`takedown.completed`

Wird einmal pro Outlet ausgeloest, wenn eine Takedown-Anfrage erfolgreich ist. Gleiche Form wie delivery.completed plus ein takedown: true-Flag.

{
  "event": "takedown.completed",
  "timestamp": "2026-05-18T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "distro_queue_id": 456,
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "outlet_id": 12,
    "outlet_name": "Spotify",
    "status": "complete",
    "takedown": true
  }
}

`release.distributed`

Wird einmal pro Release ausgeloest, wenn die Release in den Zustellzustand distributed wechselt. Wird nur beim Uebergang zu distributed ausgeloest, nicht bei nachfolgenden Speicherungen, waehrend die Release bereits distributed ist.

{
  "event": "release.distributed",
  "timestamp": "2026-05-18T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "release_title": "Summer EP",
    "delivery_status": "distributed"
  }
}

`release.review.status_changed`

Wird ausgeloest, wenn eine Release zwischen Pruefungszustaenden wechselt.

{
  "event": "release.review.status_changed",
  "timestamp": "2026-05-18T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "release_title": "Summer EP",
    "previous_status": "to_review",
    "new_status": "approved"
  }
}

Feld	Typ	Beschreibung
`previous_status`	string	Vorheriger Status. Einer von `draft`, `to_review`, `approved`, `rejected`, `require_changes`, `audit`
`new_status`	string	Neuer Status. Gleicher Wertesatz
`review_issues`	array (optional)	Nur bei Uebergaengen zu `require_changes` und `rejected` vorhanden: die Probleme, die Ihre Aufmerksamkeit erfordern. Bei jedem anderen Uebergang fehlt der Schluessel, gehen Sie also nicht davon aus, dass er immer vorhanden ist

`release.preflight.report_ready`

Wird ausgeloest, wenn der Qualitaetsbericht von Preflight QC fuer ein Release in der Wartephase vor der Pruefung zum Abruf bereit ist. Erfordert die Preflight-QC-Zusatzoption in Ihrem Konto.

{
  "event": "release.preflight.report_ready",
  "timestamp": "2026-07-07T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "release_title": "Summer EP",
    "generated_at": "2026-07-07T09:58:12+00:00",
    "profile": { "name": "quality_report", "version": 2 },
    "counts": { "blocking": 1, "informational": 2, "requires_feedback": 1 }
  }
}

Feld	Typ	Beschreibung
`release_id`	integer	Das Release, zu dem der Bericht gehoert
`label_id`	integer	Das besitzende Label der Release
`release_cat`	string \| null	Ihre Release-Katalog-Referenz
`release_title`	string \| null	Der Release-Titel
`generated_at`	string	Wann die Pruefungen abgeschlossen wurden (ISO 8601). Entspricht `report.generated_at` des Qualitaetsbericht-Endpunkts
`profile`	object	Das Qualitaetsprofil, ueber das die Zaehlungen berechnet wurden: `{name, version}`
`counts`	object	Nur aggregierte Zaehlungen: `{blocking, informational, requires_feedback}`. Die Zaehlung `requires_feedback` ueberschneidet sich mit den beiden anderen

`stream_radar.flag_created`

Ausgeloest, wenn eine Stream-Radar-Meldung erstellt wird – entweder eine ganz neue Meldung oder eine zuvor aufgeloeste Meldung, die bei einer neuen Erkennung erneut geoeffnet wird. Erfordert die Stream-Radar-Zusatzoption in Ihrem Konto. Das Feld transition unterscheidet die beiden Faelle: published fuer eine neue Meldung, reopened fuer eine wieder aktiv gewordene Meldung.

{
  "event": "stream_radar.flag_created",
  "timestamp": "2026-07-07T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "flag_id": 4501,
    "dsp": "spotify",
    "isrc": "USRC12345678",
    "release_id": 789,
    "track_id": 654,
    "severity": "high",
    "status": "active",
    "transition": "published",
    "first_detected_at": "2026-07-06T00:00:00+00:00",
    "last_detected_at": "2026-07-07T00:00:00+00:00",
    "estimated_affected_streams": 12500,
    "published_at": "2026-07-07T09:58:12+00:00",
    "resolved_at": null
  }
}

Feld	Typ	Beschreibung
`flag_id`	integer	Die stabile Kennung der Meldung; entspricht `id` auf den Stream-Radar-Endpunkten
`dsp`	string	Die Plattform, auf der das Muster beobachtet wurde (z. B. `spotify`)
`isrc`	string	Der ISRC der betroffenen Aufnahme
`release_id`	integer	Das Release, zu dem die Aufnahme gehoert
`track_id`	integer \| null	Der konkrete Track, wenn der ISRC eindeutig einem Ihrer Tracks zugeordnet ist
`severity`	string	`low`, `medium` oder `high`
`status`	string	`active` fuer dieses Ereignis
`transition`	string	`published` fuer eine neue Meldung, `reopened`, wenn eine aufgeloeste Meldung wieder aktiv geworden ist
`first_detected_at`	string \| null	Wann das Muster fuer diesen Track und diese Plattform erstmals beobachtet wurde (ISO 8601)
`last_detected_at`	string \| null	Die juengste Erkennung (ISO 8601)
`estimated_affected_streams`	integer \| null	Eine Schaetzung, wie viele Streams beteiligt sind
`published_at`	string	Wann Ihnen die Meldung erstmals gemeldet wurde (ISO 8601)
`resolved_at`	string \| null	`null`, solange die Meldung aktiv ist

`stream_radar.flag_resolved`

Ausgeloest, wenn eine Stream-Radar-Meldung aufgeloest wird, weil die Erkennungen aufgehoert haben. Erfordert die Stream-Radar-Zusatzoption. Dieselben Felder wie stream_radar.flag_created (ohne transition), mit status auf resolved und gesetztem resolved_at.

{
  "event": "stream_radar.flag_resolved",
  "timestamp": "2026-07-14T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "flag_id": 4501,
    "dsp": "spotify",
    "isrc": "USRC12345678",
    "release_id": 789,
    "track_id": 654,
    "severity": "high",
    "status": "resolved",
    "first_detected_at": "2026-07-06T00:00:00+00:00",
    "last_detected_at": "2026-07-12T00:00:00+00:00",
    "estimated_affected_streams": 18700,
    "published_at": "2026-07-07T09:58:12+00:00",
    "resolved_at": "2026-07-14T09:55:03+00:00"
  }
}

`payment.statement_ready`

Wird ausgeloest, wenn eine Zahlungsabrechnung generiert und zur Ansicht bereit ist.

{
  "event": "payment.statement_ready",
  "timestamp": "2026-05-18T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "payment_request_id": 1024,
    "invoice_number": "INV-2026-001",
    "period": "2026-04-30",
    "amount": 1234.56,
    "total_due_usd": 1234.56,
    "currency": "USD"
  }
}

Feld	Typ	Beschreibung
`payment_request_id`	integer	Interne Zahlungsanforderungs-ID
`invoice_number`	string	Rechnungsreferenz fuer die Abrechnung
`period`	string \| null	Ende-des-Zeitraums-Datum (ISO-8601-Datum, `YYYY-MM-DD`)
`amount`	number	Abrechnungsbetrag in der Waehrung `currency`
`total_due_usd`	number	Abrechnungssumme umgerechnet in USD
`currency`	string	ISO-4217-Waehrungscode (Standard `USD`)

`transcode.completed` und `transcode.failed`

Wird ausgeloest, wenn das Audio-Transcoding eines Tracks abgeschlossen wird. transcode.completed wird bei Erfolg ausgeloest; transcode.failed wird ausgeloest, wenn das Transcoding fehlschlaegt oder unvollstaendig endet. Beide haben dieselbe Payload-Form.

{
  "event": "transcode.completed",
  "timestamp": "2026-07-07T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "release_id": 789,
    "label_id": 321,
    "track_id": 654,
    "transcoder_queue_id": 987,
    "status": "complete",
    "status_message": "transcode_complete",
    "files": [
      { "asset_type_id": 2, "status": "complete" }
    ]
  }
}

Feld	Typ	Beschreibung
`release_id`	integer	Das Release, zu dem der Track gehoert
`label_id`	integer	Das besitzende Label der Release
`track_id`	integer	Der Track, der transcodiert wurde
`transcoder_queue_id`	integer	Interne Transcoder-Queue-ID
`status`	string	Roher Queue-Status: `complete`, `error` oder `incomplete`
`status_message`	string	Sicherer, aufgezaehlter Grundcode: `transcode_complete`, `transcode_error` oder `transcode_incomplete`
`files`	array	Details pro Datei fuer den Track: `{asset_type_id, status}` je transcodierter Datei

`distribution.outlet.status_changed`

Wird bei jedem Statuswechsel des Vertriebs pro Outlet ausgeloest (zum Beispiel scheduled → transcoding → batched → complete), nicht nur bei den finalen, die von delivery.completed, delivery.failed und takedown.completed abgedeckt werden. Dieses Ereignis ist absichtlich gespraechig: Abonnieren Sie es nur, wenn Sie den vollstaendigen Verlauf pro Outlet wuenschen.

{
  "event": "distribution.outlet.status_changed",
  "timestamp": "2026-07-07T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "distro_queue_id": 456,
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "outlet_id": 12,
    "outlet_name": "Spotify",
    "previous_status": "transcoding",
    "status": "batched"
  }
}

Feld	Typ	Beschreibung
`distro_queue_id`	integer	Interne Queue-ID fuer diese Zustellung
`release_id`	integer	Das Release, das vertrieben wird
`label_id`	integer	Das besitzende Label der Release
`release_cat`	string \| null	Ihre Release-Katalog-Referenz
`outlet_id`	integer \| null	Die Outlet-Ziel-ID
`outlet_name`	string \| null	Lesbarer Outlet-Name
`previous_status`	string \| null	Der vorherige Status; `null`, wenn die Zeile keinen erkannten vorherigen Status hatte
`status`	string	Der neue Status

Webhook-Signaturen verifizieren

Jede Webhook-Zustellung wird signiert, damit Sie verifizieren koennen, dass sie tatsaechlich von LabelGrid stammt. Verifizieren Sie die Signatur immer, bevor Sie das Ereignis verarbeiten.

Request-Header

Jeder Webhook-POST-Request enthaelt diese Header:

Header	Beschreibung
`X-Webhook-Signature`	HMAC-SHA256 des Roh-Request-Bodys, in Kleinbuchstaben-Hexadezimal, ohne Algorithmus-Praefix
`X-Webhook-Timestamp`	Praktische Kopie der `timestamp`-Eigenschaft im Body. Nicht von der Signatur abgedeckt — entscheiden Sie damit niemals, ob eine Zustellung aktuell ist.
`X-Webhook-Event`	Ereignis-Identifier (z. B. `delivery.completed`)
`X-Webhook-Id`	Die ID der Webhook-Konfiguration, die die Zustellung empfängt (keine ID der einzelnen Zustellung)
`User-Agent`	`LabelGrid-Webhooks/1.0`
`Content-Type`	`application/json`

Algorithmus

Algorithmus: HMAC-SHA256
Encoding: Hexadezimal in Kleinbuchstaben
Praefix: Keiner — der Wert ist nur der Hex-Digest, nicht sha256=...
Signierter Inhalt: Der vollstaendige rohe JSON-Request-Body — und sonst nichts. Kein Header wird signiert.

Der Body enthält seine eigene timestamp-Eigenschaft, dieser Wert ist also durch die Signatur geschützt. Der Header X-Webhook-Timestamp ist lediglich eine Kopie davon, die der Bequemlichkeit halber mitgeschickt wird; wer eine Zustellung abfängt, kann den Header beliebig ändern, ohne die Signatur ungültig zu machen. Aktualitätsprüfungen müssen timestamp deshalb aus dem geparsten Body lesen, niemals aus dem Header.

Verifizierungs-Rezept

Lesen Sie den Roh-Request-Body, bevor JSON geparst oder transformiert wird. Eine Re-Serialisierung des geparsten JSON kann andere Bytes erzeugen und die Signatur ungueltig machen.
Berechnen Sie HMAC-SHA256(roh_body, ihr_webhook_secret) und nehmen Sie den Hex-Digest in Kleinbuchstaben.
Vergleichen Sie mit X-Webhook-Signature mithilfe eines konstanten Zeitvergleichs. Stoppen Sie hier, wenn er nicht übereinstimmt.
Erst jetzt parsen Sie den Body und lehnen den Request ab, wenn dessen timestamp-Eigenschaft älter als Ihr Replay-Toleranzfenster ist — wir empfehlen 5 Minuten. Weil dieser Wert signiert ist, kann ein Angreifer ihn nicht auffrischen, um eine abgefangene Zustellung aktuell erscheinen zu lassen.

Jeder Wiederholungsversuch wird erneut mit einem neuen timestamp signiert, sodass ein 5-Minuten-Fenster niemals eine legitime Wiederholung ablehnt, wie spät im Backoff-Plan sie auch eintrifft.

PHP-Beispiel

$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

$expected = hash_hmac('sha256', $rawBody, $webhookSecret);

if (! hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Ungueltige Signatur');
}

// Erst parsen, nachdem die Bytes als authentisch nachgewiesen sind.
$payload = json_decode($rawBody, true);

// Die Aktualität stammt aus dem SIGNIERTEN Zeitstempel im Body,
// niemals aus dem Header X-Webhook-Timestamp.
if (! isset($payload['timestamp'])
    || abs(time() - strtotime($payload['timestamp'])) > 300) {
    http_response_code(401);
    exit('Veraltete Zustellung');
}

// ... Ereignis verarbeiten (siehe „Wiederholte Zustellungen verarbeiten“ unten)
http_response_code(200);

Node.js-Beispiel

const crypto = require('crypto');

// Express: Roh-Body VOR jeglicher JSON-Middleware erfassen
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body; // Buffer
  const signature = req.header('X-Webhook-Signature') || '';

  const expected = crypto
    .createHmac('sha256', webhookSecret)
    .update(rawBody)
    .digest('hex');

  const sigBuf = Buffer.from(signature, 'hex');
  const expBuf = Buffer.from(expected, 'hex');

  if (sigBuf.length !== expBuf.length || !crypto.timingSafeEqual(sigBuf, expBuf)) {
    return res.status(401).send('Ungueltige Signatur');
  }

  // Erst parsen, nachdem die Bytes als authentisch nachgewiesen sind.
  const payload = JSON.parse(rawBody.toString('utf8'));

  // Die Aktualität stammt aus dem SIGNIERTEN Zeitstempel im Body,
  // niemals aus dem Header X-Webhook-Timestamp.
  const sentAt = new Date(payload.timestamp).getTime();

  if (Number.isNaN(sentAt) || Math.abs(Date.now() - sentAt) > 5 * 60 * 1000) {
    return res.status(401).send('Veraltete Zustellung');
  }

  // ... Ereignis verarbeiten (siehe „Wiederholte Zustellungen verarbeiten“ unten)
  res.sendStatus(200);
});

Python-Beispiel

import hmac, hashlib, json
from datetime import datetime, timezone

raw_body = request.get_data()  # Flask: bytes, vor jeglichem JSON-Parsing
signature = request.headers.get('X-Webhook-Signature', '')

expected = hmac.new(
    webhook_secret.encode('utf-8'),
    raw_body,
    hashlib.sha256
).hexdigest()

if not hmac.compare_digest(expected, signature):
    return ('Ungueltige Signatur', 401)

payload = json.loads(raw_body)  # erst parsen, wenn die Bytes echt sind

delivery_time = datetime.fromisoformat(payload['timestamp'])  # der SIGNIERTE Wert, nie der Header
if abs((datetime.now(timezone.utc) - delivery_time).total_seconds()) > 300:
    return ('Veraltete Zustellung', 401)

return ('', 200)  # Ereignis verarbeiten, dann bestaetigen

Haeufige Fallstricke

Aktualitätsprüfung anhand des Headers X-Webhook-Timestamp. Der Header wird nicht signiert. Wer eine Zustellung abfängt, kann denselben Body mit derselben Signatur und einem frischen Header-Wert erneut senden und eine header-basierte Prüfung dauerhaft bestehen. Lesen Sie timestamp stattdessen aus dem geparsten Body — dieser Wert ist signiert.
Re-Serialisieren des Bodys vor dem Hashing. Frameworks, die JSON automatisch parsen (Express express.json(), Laravels Standard-Request-Body), verlieren die Original-Bytes. Erfassen Sie zuerst den Roh-Body.
Verwenden eines nicht zeitkonstanten Vergleichs (==, ===). Anfaellig fuer Timing-Angriffe — verwenden Sie immer hash_equals (PHP), crypto.timingSafeEqual (Node), hmac.compare_digest (Python) oder das Aequivalent Ihrer Sprache.
Erwarten eines sha256=-Praefix. Der Header-Wert ist nur der Hex-Digest ohne Praefix.
Überspringen der Aktualitätsprüfung. Ohne sie kann eine abgefangene Zustellung unbegrenzt gegen Ihren Endpunkt wiederholt werden.
X-Webhook-Id als Zustellungs-ID betrachten. Sie identifiziert die Webhook-Konfiguration, nicht die einzelne Zustellung, und ist ebenfalls nicht signiert.

Wiederholte Zustellungen verarbeiten

Die Webhook-Zustellung erfolgt mindestens einmal: Eine Zustellung, die Ihr Endpunkt tatsächlich verarbeitet hat, kann erneut eintreffen, wenn Ihre 2xx-Antwort verloren ging oder erst nach dem 10-Sekunden-Timeout ankam und LabelGrid sie daraufhin wiederholt. Die Signaturprüfung belegt, dass eine Anfrage echt ist — sie belegt nicht, dass Sie sie noch nicht verarbeitet haben.

Zustellungen tragen keine eindeutige ID pro Zustellung; bilden Sie deshalb einen eigenen Idempotenzschlüssel aus dem signierten Payload. Der Ereignistyp plus die Bezeichner in data genügen in der Regel — zum Beispiel delivery.completed plus distro_queue_id oder transcode.completed plus track_id. Halten Sie den Schlüssel fest, wenn Sie ein Ereignis verarbeiten, und ignorieren Sie alles, was Sie bereits festgehalten haben.

Verwenden Sie dafür weder die Signatur noch den timestamp. Jeder Versuch wird im Moment des Versands neu signiert, sodass die Wiederholung eines bereits verarbeiteten Ereignisses mit einem anderen timestamp und einer anderen Signatur eintrifft — der Schlüssel muss aus den Bezeichnern des Ereignisses selbst stammen.

Kombinieren Sie das mit der Aktualitätsprüfung oben: Die Aktualität begrenzt, wie lange eine abgefangene Zustellung wiederholbar bleibt, und Idempotenz macht eine Wiederholung harmlos — ob sie nun von einem Wiederholungsversuch oder von einem Angreifer innerhalb des Fensters stammt.

Limits und Zuverlaessigkeit

Request-Limits

Limit	Wert
Request-Timeout	10 Sekunden
Maximale Payload-Groesse	64 KB
Maximale Anzahl Webhooks pro Benutzer	10

Wenn Ihr Endpunkt nicht innerhalb von 10 Sekunden antwortet, wird die Zustellung als Fehler behandelt und wiederholt.

Wiederholungsplan

Wenn Ihr Endpunkt einen Non-2xx-Status zurueckgibt oder einen Timeout hat, wiederholt LabelGrid mit exponentiellem Backoff:

Versuch	Wartezeit vor Wiederholung
1 → 2	30 Sekunden
2 → 3	1 Minute
3 → 4	2 Minuten
4 → 5	4 Minuten
5 → 6	8 Minuten
6 → 7	16 Minuten
7 → 8	32 Minuten
8 → 9	64 Minuten
9 → 10	128 Minuten

Jedes Intervall enthaelt 0–30 Sekunden Jitter. Nach 10 Versuchen (~4,5 Stunden Gesamtdauer) wird die Zustellung als dauerhaft fehlgeschlagen protokolliert und nicht weiter wiederholt.

Automatische Deaktivierung

Wenn der Endpunkt eines Webhooks wiederholt fehlschlaegt — mehrere fehlgeschlagene Zustellungen ohne eine einzige erfolgreiche dazwischen —, deaktiviert LabelGrid den Webhook automatisch, um einen Endpunkt nicht weiter anzusteuern, der offensichtlich keine Ereignisse empfangen kann. Der Fehlerzaehler wird bei jeder erfolgreichen Zustellung zurueckgesetzt, sodass ein gelegentlicher Aussetzer einen Webhook nie deaktiviert; nur anhaltendes, ununterbrochenes Fehlschlagen tut dies.

Wenn ein Webhook auf diese Weise deaktiviert wird, erhaelt sein Eigentuemer eine E-Mail. Die E-Mail nennt den Namen des Webhooks und die URL seines Endpunkts sowie die Art des Fehlers, der die Deaktivierung ausgeloest hat — zum Beispiel eine Zeitueberschreitung der Verbindung oder wiederholte HTTP-Fehler.

Die Reaktivierung erfolgt im Selfservice: Beheben Sie Ihren Endpunkt und schalten Sie den Webhook anschliessend unter Profil → Webhooks wieder ein. Die Reaktivierung eines deaktivierten Webhooks setzt seinen Fehlerzaehler zurueck. Die Webhook-Liste zeigt den aktiven Status und den aktuellen Fehlerzaehler jedes Webhooks, sodass Sie einen fehlerhaften Endpunkt auf einen Blick erkennen.

Best Practices fuer Zuverlaessigkeit

Geben Sie schnell eine 2xx-Antwort zurueck (innerhalb von 10 Sekunden)
Verarbeiten Sie die Daten asynchron nach der Bestaetigung
Verifizieren Sie die Signatur bei jeder Anfrage (siehe Webhook-Signaturen verifizieren)
Machen Sie Ihren Handler idempotent — die Zustellung erfolgt mindestens einmal (siehe Wiederholte Zustellungen verarbeiten)
Ueberwachen Sie Ihren Fehlerzaehler in der Webhook-Liste
Pruefen Sie die Zustell-Logs, wenn Sie verpasste Ereignisse untersuchen

Anwendungsfaelle

Automatisierte Benachrichtigungen

Slack-Nachrichten senden, wenn Releases live gehen
Ihr Team per E-Mail benachrichtigen, wenn Lieferungen fehlschlagen
Interne Dashboards aktualisieren

Workflow-Automatisierung

Marketing-Kampagnen ausloesen, wenn Releases verteilt werden
Ihre Website aktualisieren, wenn neue Inhalte verfuegbar sind
Status mit externen Projektmanagement-Tools synchronisieren

Ueberwachung und Alarmierung

Sofortige Benachrichtigungen bei Lieferfehlern erhalten
Vertriebsfortschritt in Echtzeit verfolgen
Review-Status-Aenderungen ueberwachen

Fehlerbehebung

Webhook empfaengt keine Ereignisse

Status pruefen - Ist der Webhook Active?
URL verifizieren - Ist der Endpunkt aus dem Internet erreichbar?
Ereignisse pruefen - Sind die richtigen Ereignisse ausgewaehlt?
Logs ueberpruefen - Sind Fehler aufgezeichnet?

Hohe Fehlerzahl

Ihren Endpunkt pruefen - Gibt er 200 OK zurueck?
Antwortzeit pruefen - Antwortet er innerhalb des Timeouts?
Fehlermeldungen ueberpruefen - Was schlaegt fehl?
Manuell testen - Einen Test-Webhook senden

Secret neu generieren

Wenn Ihr Webhook-Secret kompromittiert ist:

Klicken Sie auf Regenerate Secret in den Webhook-Einstellungen
Aktualisieren Sie Ihre Anwendung mit dem neuen Secret
Das alte Secret funktioniert sofort nicht mehr

Brauchen Sie Hilfe?

Wenn Sie Fragen zu Webhooks haben, kontaktieren Sie unser Support-Team.

Sie nutzen LabelGrid noch nicht?

Alles, was Sie gerade gelesen haben, steht Ihnen auf unserer Plattform zur Verfügung.

Entdecken Sie, was LabelGrid kann →