Webhook API

sellerfox sendet ausgewählte KPI-Daten täglich als JSON per HTTPS-POST an deinen Endpunkt. Diese Referenz beschreibt Request-Header, Payload-Schema, Authentifizierung und Zustellverhalten.

Konfiguration, KPI-Auswahl und Verwaltung im Dashboard sind unter Webhooks beschrieben.

HTTP-Request

Der folgende Request zeigt eine Zustellung mit Bearer-Authentifizierung an eine Beispieladresse. Ersetze Host und Pfad durch deinen Empfänger.

POST /sellerfox/webhooks HTTP/1.1
Host: receiver.example.com
Content-Type: application/json
Authorization: Bearer <configured-token>
X-Webhook-ID: 65abc123def4567890123456
X-Webhook-Delivery-ID: 550e8400-e29b-41d4-a716-446655440000

HTTPS-Endpunkt vorbereiten

Die gespeicherte URL muss syntaktisch gültig und öffentlich erreichbar sein. Die URL muss https: verwenden und als Host eine Domain statt einer IPv4- oder IPv6-Adresse enthalten. sellerfox lehnt lokale und interne Adressen ab. Für lokale Tests brauchst du einen öffentlich erreichbaren Tunnel.

Request-Header

Header jeder Zustellung

Feld	Enthalten	Typ	Beschreibung
Content-Type	Immer	string	Immer application/json.
X-Webhook-ID	Immer	string	ID der gespeicherten Webhook-Konfiguration; bei einem Test vor dem Speichern wird test-webhook verwendet.
X-Webhook-Delivery-ID	Immer	string	Neue ID für jeden HTTP-Versuch.
Authorization	Bedingt	string	Nur vorhanden, wenn für den Webhook Bearer Token oder Basic Auth konfiguriert ist.

Den Teststatus liest du aus dem Body-Feld test. Für jeden HTTP-Versuch, Retry und Test entsteht eine neue X-Webhook-Delivery-ID. Protokolliere die X-Webhook-Delivery-ID zur Nachverfolgung, aber verwende die X-Webhook-Delivery-ID nicht, um mehrere Retries als dieselbe Zustellung zu erkennen.

Zustellungen authentifizieren

Authentifizierungsmodi

Modus	Zugangsdaten	Was sellerfox sendet
Keine	Keine	keinen Authorization-Header
Bearer Token	Token	Authorization: Bearer <configured-token>
Basic Auth	Benutzername und Passwort	Authorization: Basic <base64(username:configured-password)>

Payload

Alle Webhook-Typen verwenden dieselbe JSON-Struktur. Dieses Beispiel zeigt einen Marktplatz-Webhook:

{
  "webhookId": "65abc123def4567890123456",
  "webhookType": "marketplace-webhook",
  "timestamp": "2026-08-13T00:00:10.000Z",
  "test": false,
  "data": [
    {
      "date": "2026-08-12",
      "Sales (Total)": 1234.56,
      "Units": 42
    }
  ],
  "metadata": {
    "workspaceId": "65abc123def4567890123457",
    "workspaceName": "Example workspace",
    "from": "2026-07-13T00:00:00.000Z",
    "to": "2026-08-12T23:59:59.999Z",
    "kpis": ["Sales (Total)", "Units"],
    "marketplaceDomain": "amazon.de"
  }
}

Gemeinsame Felder

Felder der Payload-Struktur (Envelope)

Feld	Enthalten	Typ	Beschreibung
webhookId	Immer	string	ID der gespeicherten Webhook-Konfiguration; bei einem Test vor dem Speichern steht hier der Wert "test-webhook".
webhookType	Immer	string	Kennung des ausgewählten Webhook-Typs.
timestamp	Immer	string	Zeitpunkt, zu dem die Payload für diesen Versuch erstellt wurde.
test	Immer	boolean	Kennzeichnet einen Test aus dem Dashboard.
data	Immer	array	Ausgewählte KPI-Zeilen; das Array darf leer sein.
metadata	Immer	object	Metadaten zu Workspace, Zeitfenster, KPIs und Bereich.

Metadatenfelder für alle Typen

Feld	Enthalten	Typ	Beschreibung
workspaceId	Immer	string	Workspace-ID.
workspaceName	Immer	string	Aktueller Workspace-Name.
from	Immer	string	Beginn des Zeitfensters (einschließlich).
to	Immer	string	Ende des Zeitfensters (einschließlich).
kpis	Immer	array	Englische Labels der KPI-Schlüssel in data, in der konfigurierten Reihenfolge.

Der timestamp gibt an, wann die Payload für den aktuellen Versuch erstellt wurde. Der timestamp ist kein Zeilendatum und kann sich bei einem Retry ändern. data ist immer ein Array und kann leer sein. metadata.from und metadata.to begrenzen das Abfragefenster einschließlich beider Grenzwerte. Typspezifische Metadaten, die für den gewählten Typ nicht gelten, fehlen vollständig und werden nicht als null gesendet.

Datenzeilen und fehlende Werte

Marktplatz- und Produktzeilen enthalten reine Datumswerte. Ein KPI ohne Wert fehlt in der jeweiligen Zeile, anstatt als null zu erscheinen. Keyword-Zeilen verwenden vollständige ISO-Zeitstempel in date und können für einen KPI null liefern. Dein Empfänger muss beide Formen verarbeiten können.

Ist metadata.marketplaceDomain vorhanden, beziehen sich alle Zeilen in data auf den dort angegebenen Marktplatz, zum Beispiel amazon.de.

KPI-Schlüssel und Einheiten

metadata.kpis listet die ausgewählten KPIs in der konfigurierten Reihenfolge auf. Die KPI-Labels in metadata.kpis und die KPI-Schlüssel in data sind immer auf Englisch, unabhängig von der Sprache im Dashboard.

Die Payload enthält keine Einheiten oder Währungsangaben, auch nicht die Zielwährung des Workspaces. Ein Schema, das die Datentypen der KPI-Werte beschreibt, wird ebenfalls nicht mitgesendet.

Schemaänderungen verarbeiten

⚠

Payloads auf Änderungen vorbereiten

Die Payload enthält kein Versionsfeld. Akzeptiere unbekannte Felder und lege Payloads mit unbekanntem Typkennzeichen zur Prüfung beiseite.

Webhook-Typen

Jeder Typ hat ein eigenes Typkennzeichen, einen festen Datenumfang und eigene Metadaten zum Bereich. Wähle den Wert von webhookType aus, um die zugehörige Beispiel-Payload und die zusätzlichen Metadaten zu prüfen. Pro Webhook kannst du zwischen einem und 20 KPIs auswählen. Wie viele Webhooks du erstellen kannst, bestimmt das Kontingent des Workspaces. Sollen mehrere Endpunkte dieselben Daten empfangen, lege mehrere Webhooks mit identischer Konfiguration und unterschiedlichen URLs an.

Marktplatz/marketplace-webhook

Liefert einmal täglich Daten für einen einzelnen Marktplatz.

KPI-Definitionen und Einheiten im KPI-Explorer nachschlagen

KPI-Limit

20

Verfügbar

136

Ausgewählter Typ: Marktplatz (marketplace-webhook)

{
  "webhookId": "65abc123def4567890123456",
  "webhookType": "marketplace-webhook",
  "timestamp": "2026-08-13T00:00:10.000Z",
  "test": false,
  "data": [
    {
      "date": "2026-08-12",
      "Sales (Total)": 1234.56,
      "Units": 42
    }
  ],
  "metadata": {
    "workspaceId": "65abc123def4567890123457",
    "workspaceName": "Example workspace",
    "from": "2026-07-13T00:00:00.000Z",
    "to": "2026-08-12T23:59:59.999Z",
    "kpis": [
      "Sales (Total)",
      "Units"
    ],
    "marketplaceDomain": "amazon.de"
  }
}

Feld	Enthalten	Typ	Beschreibung
marketplaceDomain	Für diesen Typ	string	Für diese Zustellung konfigurierte Domain des Marktplatzes.

Response und Limits

sellerfox folgt höchstens fünf Redirects und wertet nur die letzte Response aus. Nur HTTP-Statuscodes von 200 bis 299 gelten als Erfolg. Bei jedem anderen Status, zu vielen Redirects, Netzwerk- oder TLS-Fehlern sowie Timeouts schlägt der Versuch fehl.

Zustellung bestätigen

Prüfe die konfigurierten Zugangsdaten, bevor du den Request annimmst. Speichere den Request dauerhaft oder lege den Request in einer dauerhaften Queue ab. Bestätige die erfolgreiche Speicherung mit 2xx, vorzugsweise mit 204. Für die Antwort hast du bei geplanten Zustellungen 30 Sekunden und bei Tests 10 Sekunden Zeit. Verarbeitungsschritte, die das Antwortzeitlimit überschreiten könnten, solltest du nach der Bestätigung ausführen. So vermeidest du Timeouts durch die Verarbeitung und zusätzliche Zustellversuche bei geplanten Webhooks. Bestätige keine Zustellung, die nur im Arbeitsspeicher liegt: Nach der Bestätigung kannst du die Zustellung nicht erneut anfordern.

Geplante Zustellung und Test im Vergleich

Geplante Requests und Test-Requests im Vergleich

Eigenschaft	Geplanter Request	Test-Request
test	false	true
Daten	Aktuelle Daten, die für diese Zustellung abgerufen wurden	Aktuelle Daten, die für diese Zustellung abgerufen wurden; keine generierten Beispieldaten
Datumsfenster	31 Tage bis einschließlich gestern	Dasselbe Fenster
Timeout	30 Sekunden	10 Sekunden
Request-Body-Limit	10 MiB	1 MiB
Response-Body-Limit	10 MiB	5 MiB
Zustellungsverlauf	Erstellt und aktualisiert	Nicht erstellt
Retries	Höchstens drei Versuche insgesamt	Keine
Erfolgs-/Fehlerzähler	Aktualisiert	Unverändert

Überschreitet dein Endpunkt das jeweilige Timeout oder eines der Größenlimits, schlägt der Versuch fehl.

Zustellung und Retries

Geplante Zustellungen starten täglich. sellerfox prüft stündlich, ob ein weiterer Zustellversuch ansteht. Warte daher einige Stunden, bevor du eine Zustellung als verloren betrachtest, und verlass dich nicht auf eine genaue Uhrzeit. Eine Zustellung umfasst höchstens drei Versuche: den ersten Request und bis zu zwei Retries.

Bei jedem Retry ruft sellerfox die aktuellen Daten erneut ab, erstellt die Payload neu und vergibt einen neuen timestamp sowie eine neue X-Webhook-Delivery-ID. Das ursprüngliche Datumsfenster bleibt dabei unverändert. Jeder fehlgeschlagene HTTP-Versuch erhöht den Zähler für aufeinanderfolgende Fehler; ein erfolgreicher Versuch setzt den Fehlerzähler zurück. Nach zehn aufeinanderfolgenden Fehlversuchen deaktiviert sellerfox den Webhook. Behebe die Ursache und stelle den Webhook wieder her, wie unter Webhooks → Zustellungen überwachen beschrieben.

Webhook- und Delivery-IDs unterscheiden

Webhook-ID: webhookId im Body und X-Webhook-ID im Header identifizieren den Webhook. Beide Felder enthalten denselben Wert, der bei Retries gleich bleibt.

ID des Zustellversuchs: X-Webhook-Delivery-ID identifiziert einen einzelnen Request und ändert sich bei jedem Retry. Protokolliere diese ID, um einzelne Versuche in deinen Logs nachzuvollziehen.

Delivery-ID im Dashboard: Die ID unter „Verlauf anzeigen“ gehört zur gesamten Zustellung und bleibt bei Retries gleich. Sie wird nicht im Request mitgesendet und lässt sich nicht mit der X-Webhook-Delivery-ID abgleichen.

Empfänger implementieren

Die Beispiele zeigen den HTTP-Empfang und die Bestätigung nach dem Einreihen in eine Queue. durableQueue und durable_queue stehen für deine eigene dauerhafte Queue. Ergänze vor dem Einsatz die Prüfung der konfigurierten Zugangsdaten und die Queue-Anbindung.

import express from 'express'

const app = express()
app.use(express.json({ limit: '10mb' }))

app.post('/sellerfox/webhooks', async (request, response) => {
  await durableQueue.add({ headers: request.headers, payload: request.body })
  response.sendStatus(204)
})

from flask import Flask, request

app = Flask(__name__)

@app.post('/sellerfox/webhooks')
def receive_webhook():
    durable_queue.put({'headers': dict(request.headers), 'payload': request.json})
    return '', 204

Sichere Upserts

Das Fenster umfasst 31 Tage bis einschließlich gestern und überschneidet sich mit dem Fenster des Vortags um 30 Tage. Bereits zugestellte Werte können sich nachträglich ändern. sellerfox führt pro Webhook und Datumsfenster genau eine Zustellung aus. Ersetze die gespeicherten Zeilen für denselben Bereich und dasselbe Datum, anstatt ausschließlich neue Datensätze anzuhängen.

Dieses Verarbeitungsmodell berücksichtigt Retries mit neu abgefragten Daten und überlappende geplante Fenster für alle Webhook-Typen.

Request empfangen

1. Zugangsdaten prüfen

   Falls konfiguriert: Bearer-Token oder Basic-Zugangsdaten prüfen.

2. Payload prüfen

   JSON lesen und sicherstellen, dass data ein Array ist.

3. Dauerhaft in die Queue schreiben

   {headers, payload} unter einer selbst erzeugten Datensatz-ID speichern.

Antwort an sellerfox

204 zurückgeben

Nach der dauerhaften Speicherung und vor Ablauf des Antwortzeitlimits.

Separat aus der Queue verarbeiten

1. Zustellversuch protokollieren

   X-Webhook-Delivery-ID zur Nachverfolgung speichern, nicht zur Deduplizierung von Retries.

2. Bereich bestimmen

   scope aus payload.webhookId, payload.webhookType und den passenden metadata-Feldern bilden.

3. Nach Datum gruppieren

   payload.data anhand von row.date gruppieren.

4. Zeilen je Gruppe ersetzen

   Für jedes {scope, date} die gespeicherten Zeilen durch die empfangenen rows ersetzen.

Die Antwort bestätigt die dauerhafte Speicherung. Die weitere Verarbeitung erfolgt getrennt davon.

Pseudocode anzeigen

receive(request):
  verify the configured Bearer or Basic credential, when one is configured
  parse JSON and require data to be an array
  durably enqueue {headers, payload} under a receiver-generated record ID
  return 204 before the sender timeout

process(headers, payload):
  record X-Webhook-Delivery-ID for observability, never as a retry deduplication key
  scope = {payload.webhookId, payload.webhookType, applicable metadata scope fields}
  groups = group payload.data by row.date
  for each {date, rows} in groups:
    replace the receiver's rows for {scope, date} with rows

Ersetze für jeden gelieferten Tag die bisherigen Zeilen durch die neu empfangenen. Dabei müssen webhookId, webhookType und die Metadaten zur Zuordnung übereinstimmen. Bei marktplatzbezogenen Webhooks gehört dazu metadata.marketplaceDomain, damit Daten verschiedener Marktplätze getrennt bleiben.

So übernimmst du nachträgliche Korrekturen und vermeidest doppelte Einträge, wenn mehrere Zustellungen denselben Tag enthalten. Das gilt für alle Webhook-Typen.

Protokollieren und überwachen

Bewahre die empfangenen Requests auf und protokolliere für jeden Request, ob dein Endpunkt ihn erfolgreich angenommen hat oder ein Fehler aufgetreten ist. So kannst du später nachvollziehen, welche Daten angekommen sind und wo Probleme auftraten. Reagiere frühzeitig auf wiederholte Fehler: Nach zehn fehlgeschlagenen Zustellversuchen in Folge deaktiviert sellerfox den Webhook.

Im Dashboard gelten folgende Grenzen:

• Antworten deines Endpunkts: Testergebnisse und Verlaufseinträge erfolgreicher geplanter Zustellungen zeigen höchstens die ersten 5.000 Zeichen der Antwort.
• Erfolgreiche Zustellungen: sellerfox löscht den Verlaufseintrag 30 Tage nach der Zustellung.
• Ausstehende und fehlgeschlagene Zustellungen: Diese Verlaufseinträge werden nicht nach 30 Tagen automatisch gelöscht.

Integration testen

Lege den Webhook wie unter Webhook erstellen und testen beschrieben an.

Empfänger testen

Starte den Test im Dashboard über „Verbindung testen“. Der Test verwendet aktuelle Daten, keine generierten Beispieldaten. Auch bei einem Fehler während des Datenabrufs kann ein gültiger Request mit data: [] entstehen.

Testest du einen Webhook vor dem Speichern, enthalten webhookId und X-Webhook-ID den Wert test-webhook. Bei einem bereits gespeicherten Webhook wird dessen ID gesendet.

Antwortet dein Empfänger mit einem Fehler, zeigt sellerfox ein strukturiertes Testergebnis. Bei Fehlern während der Vorbereitung oder des Versands kann stattdessen ein allgemeiner Fehlerhinweis ohne weitere Details erscheinen.

Request mit cURL senden

Speichere eine Beispiel-Payload als payload.json und ersetze URL und Token durch die Werte deines Empfängers. Damit prüfst du die Verarbeitung am Endpunkt; der Dashboard-Test oben prüft zusätzlich die Zustellung durch sellerfox.

curl -i -X POST https://receiver.example.com/sellerfox/webhooks \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <configured-token>' \
  --data-binary @payload.json

Verwandte Themen

• Webhooks – Zustellungen im Dashboard konfigurieren, testen und überwachen.
• Troubleshooting – fehlgeschlagene Tests und ausbleibende Zustellungen untersuchen.
• KPI-Explorer – KPI-Definitionen und Einheiten nachschlagen.
• Datenaktualisierung – nachsehen, wann sich die Daten hinter einer Zustellung ändern.