Webhooks

Statt regelmäßig abzufragen, registrierst du einen HTTPS-Endpoint, und Nembol sendet dir per POST ein Event, sobald etwas passiert: Eine neue Bestellung kommt von einem beliebigen Kanal an, ein Bestand ändert sich, ein Angebot geht live oder schlägt fehl.

Erstelle Endpoints im Dashboard (Einstellungen → Entwickler → Webhooks) oder über die API. Jeder Endpoint hat ein Signatur-Secret, das einmal bei der Erstellung angezeigt wird.

Die Zustellung

POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: Nembol-Webhooks/1.0 (+https://developers.nembol.com/docs/webhooks)
X-Nembol-Event-Id: evt_2c91…
X-Nembol-Signature: t=1784900412,v1=5257a869e7…

{
  "id": "evt_2c91…",
  "type": "order.created",
  "api_version": "2026-07-24",
  "store_id": "5f2a…",
  "account_id": "acct_66f0a1",
  "created_at": "2026-07-24T16:03:12Z",
  "data": {
    "object": { "id": "ord_…", "channel": "etsy", "total": "49.90", "currency": "USD" }
  }
}

account_id gibt es nur für Partner, und zwar bei jedem Event eines ihrer Unternehmen (bei Zustellungen wie bei GET /events, operation.completed eingeschlossen): Es sagt, zu welchem Unternehmen das Event gehört (dieselbe ID wie in GET /accounts). Events deines eigenen Shops haben es nicht. Leite danach weiter.

Jede Zustellung enthält User-Agent: Nembol-Webhooks/1.0 und die Event-ID in X-Nembol-Event-Id. Vertraue der Signatur, nicht diesen Headern: Sie sind für deine Logs und Firewall-Regeln gedacht. Eine Zustellung wird einmal pro Endpoint gesendet (Wiederholungen nur bei erneuten Versuchen nach einer Nicht-2xx-Antwort, mit derselben Event-ID).

data.object ist die vollständige Ressource in dem Zustand, in dem das Event zugestellt wird (oder aus GET /events gelesen wird), keine Kopie, die zum Zeitpunkt der Änderung eingefroren wurde. Was sich geändert hat, steht in data selbst: z. B. data.status und data.previous_status bei listing.status_changed. Hat sich die Ressource zwischendurch erneut geändert, zeigt data.object bereits den neueren Zustand, und ein neueres Event folgt; ordne deine Aktualisierungen nach dem created_at des Events.

Der Vertrag (lies ihn zweimal)

• At-least-once: Dasselbe Event kann mehr als einmal zugestellt werden. Dedupliziere anhand von event.id.
• Keine garantierte Reihenfolge: Events können in anderer Reihenfolge ankommen. Verwende created_at (oder lade die Ressource neu), statt eine Abfolge anzunehmen.
• Jedes Event wird zugestellt, egal welcher Teil von Nembol es erzeugt hat (API-Aufruf, Dashboard, Bestellsynchronisierung, Kanal-Webhook). Konnte die Zustellung eines Events bei seiner Erstellung nicht eingereiht werden, reiht Nembol sie innerhalb weniger Minuten ein (Events bis zu 24 Stunden alt): Es kommt verspätet an, aber nie gar nicht. Ein Endpoint erhält nur Events, die nach ihm erstellt wurden. GET /events bleibt der Weg für den Abgleich.
• Unbekannte Typen: Mit der Zeit kommen neue Event-Typen hinzu. Ignoriere Typen, die du nicht behandelst, und antworte trotzdem mit 2xx.
• Antworte schnell mit 2xx: innerhalb von 10 Sekunden, sonst gilt die Zustellung als fehlgeschlagen. Erledige die eigentliche Arbeit asynchron: einreihen, dann 200 zurückgeben.
• Prüfe die Signatur, bevor du irgendetwas vertraust: Signaturen prüfen.

Wiederholungen

Fehlgeschlagene Zustellungen (Nicht-2xx, Timeout, Verbindungsfehler) werden mit exponentiellem Backoff wiederholt: 1 Min. → 5 Min. → 30 Min. → 2 Std. → 12 Std. (etwa 15 Stunden), danach wird die Zustellung als fehlgeschlagen markiert. Schlägt ein Endpoint dauerhaft fehl, wird er automatisch deaktiviert, und der Shop-Inhaber wird im Dashboard und per E-Mail benachrichtigt. Jeder Versuch ist im Zustellprotokoll des Dashboards sichtbar, mit manuellem Erneut zustellen.

Ein Zeitfenster komplett verpasst? Gleiche über die Event-Log-API ab: GET /events?created_after=… gibt die Events der letzten 30 Tage zurück.

Zuletzt aktualisiert am 20. Oktober 2026