Alle Artikel Erste Schritte Pipeline einrichten Shop-Integrationen Feldmapping JSON-Webhooks Bestellungen verwalten API-Zugang API-Referenz Sicherheit Audit-Log

JSON-Webhooks

Der JSON-Webhook-Endpunkt ist der zentrale Eingang für Bestellungen von Shopsystemen und beliebigen JSON-Quellen. Er unterstützt sowohl XML- als auch JSON-Payloads und bietet mehrere Authentifizierungsmethoden.

Webhook-URL

Jede Pipeline hat eine eigene Webhook-URL:

POST https://orderport.app/api/v1/webhook/{token}

Das {token} ist ein eindeutiger UUID-Token, der bei der Pipeline-Erstellung generiert wird. Sie finden die URL auf der Pipeline-Detailseite.

Tipp: Kopieren Sie die URL direkt aus der Pipeline-Detailseite. Der Token ist lang und sollte nicht manuell abgetippt werden.

Authentifizierung

Bearer Token

Bei dieser Methode sendet Ihr System einen Token im Authorization-Header:

POST https://orderport.app/api/v1/webhook/{token}
Authorization: Bearer ot_bearer_a1b2c3d4...
Content-Type: application/json

{ "order": { ... } }

Einrichtung:

  1. Erstellen Sie eine Credential auf der Pipeline-Detailseite
  2. Wählen Sie Bearer Token als Authentifizierungstyp
  3. Orderport generiert automatisch einen Token (Format: ot_bearer_...)
  4. Oder geben Sie einen eigenen Token ein (min. 8 Zeichen)

Wichtig: Der Token wird nur einmal angezeigt. Kopieren Sie ihn sofort und hinterlegen Sie ihn in Ihrem Shopsystem.

HMAC-SHA256 Signatur

Bei dieser Methode signiert Ihr System den Request-Body mit einem geheimen Schlüssel. Orderport prüft die Signatur im konfigurierten HTTP-Header.

POST https://orderport.app/api/v1/webhook/{token}
X-Shopware-Signature: a1b2c3d4e5f6...
Content-Type: application/json

{ "order": { ... } }

Die Signatur wird berechnet als:

HMAC-SHA256(request_body, shared_secret)

Einrichtung:

  1. Erstellen Sie eine Credential auf der Pipeline-Detailseite
  2. Wählen Sie HMAC-SHA256 als Authentifizierungstyp
  3. Geben Sie den Header-Namen an, in dem die Signatur gesendet wird (z. B. X-Shopware-Signature, X-Shopify-Hmac-Sha256, X-WC-Webhook-Signature)
  4. Orderport generiert automatisch ein Secret (Format: ot_hmac_...)
  5. Hinterlegen Sie das Secret in Ihrem Shopsystem

Shopware 6 sendet die HMAC-Signatur im Header X-Shopware-Signature. Shopify nutzt X-Shopify-Hmac-Sha256. WooCommerce nutzt X-WC-Webhook-Signature.

Ohne Authentifizierung

Wenn keine Credential angelegt ist, akzeptiert der Webhook-Endpunkt alle Anfragen mit gültigem Pipeline-Token. Dies ist nur für Tests empfohlen.

Request-Format

Der Webhook-Endpunkt akzeptiert:

Content-Type Behandlung
application/json JSON-Payload, wird durch den shopspezifischen Normalizer verarbeitet
application/xml, text/xml XML-Payload, wird wie der cXML-Endpunkt behandelt

Antwort bei Erfolg

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "message_id": 456,
  "status": "queued"
}

Die Bestellung wurde empfangen und wird asynchron verarbeitet.

Fehlerfälle

HTTP-Status Bedeutung
401 Unauthorized Ungültige oder fehlende Authentifizierung
403 Forbidden Pipeline inaktiv oder Credential deaktiviert
404 Not Found Ungültiger Pipeline-Token
406 Not Acceptable Ungültiger Content-Type
409 Conflict Duplikat – Bestellung mit dieser ID wurde bereits empfangen
413 Payload Too Large Payload größer als 5 MB
422 Unprocessable Leerer oder ungültiger Payload

REST API Transport (ausgehend)

Wenn Ihr Zielsystem eine REST-API ist, können Sie den Transporttyp REST API wählen. Damit sendet Orderport die transformierten Daten als JSON an Ihre API.

Konfiguration

Feld Beschreibung
URL Die Ziel-URL Ihrer API (z. B. https://api.ihr-erp.de/orders)
HTTP-Methode POST, PUT oder PATCH
Authentifizierung Keine, Basic Auth, Bearer Token oder API-Key-Header

Auth-Typen

Keine Authentifizierung: Orderport sendet den Request ohne Auth-Header.

Basic Auth: Benutzername und Passwort werden als Authorization: Basic ...-Header gesendet.

Bearer Token: Ein Token wird als Authorization: Bearer {token}-Header gesendet. Der Token wird verschlüsselt in der Datenbank gespeichert.

API-Key-Header: Ein benutzerdefinierter Header (z. B. X-API-Key) wird mit dem konfigurierten API-Key gesendet. Der Key wird verschlüsselt gespeichert.

Beispiel-Konfiguration

Transport-Typ: REST API
URL: https://api.ihr-erp.de/v2/orders
Methode: POST
Auth: Bearer Token
Token: eyJhbGciOiJIUzI1NiJ9...

Orderport sendet dann:

POST https://api.ihr-erp.de/v2/orders
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...
Content-Type: application/json

{
  "order": {
    "id": "ORD-2024-001",
    "date": "2024-03-08",
    ...
  }
}

Duplikat-Erkennung

Orderport erkennt doppelt gesendete Bestellungen automatisch. Wenn eine neue Bestellung mit derselben Bestell-ID bereits existiert, wird keine neue Nachricht erstellt.

JSON-Payloads erhalten HTTP 409 Conflict:

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "message_id": 42,
  "status": "duplicate",
  "message": "Bestellung bereits empfangen."
}

XML-Payloads erhalten HTTP 200 mit cXML-Status 409:

<Status code="409" text="Conflict">Bestellung bereits empfangen. Message-ID: 42</Status>

Hinweis: Update- und Delete-Bestellungen werden nie als Duplikat behandelt. Nur neue Bestellungen (type="new") werden geprüft. Fehlgeschlagene Bestellungen können mit derselben ID erneut gesendet werden.

Unterschied: cXML-Webhook vs. JSON-Webhook

Eigenschaft cXML-Webhook JSON-Webhook
URL /api/v1/cxml/{token} /api/v1/webhook/{token}
Content-Type application/xml application/json oder application/xml
Authentifizierung SharedSecret im XML-Header Bearer Token oder HMAC-Signatur
Antwortformat cXML-Response (XML) JSON
Gedacht für Ariba, Coupa, SAP Shopware, Shopify, WooCommerce

Nächste Schritte

Vorheriger Artikel Feldmapping Nächster Artikel Bestellungen verwalten