# JSON-Webhooks

Der JSON-Webhook-Endpunkt ist der zentrale Eingang für Bestellungen von Shopsystemen und beliebigen JSON-Quellen — und für Belege (Bestellbestätigung, Rechnung, Gutschrift), die Orderport als cXML weiterleitet. 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`.

### API-Key des Accounts

Statt einer Credential pro Pipeline kann Ihr System einen [API-Key](/docs/api-zugang) senden. Ein API-Key gilt für die Webhooks **aller** Pipelines Ihres Accounts — praktisch, wenn ein System mehrere Pipelines beliefert (z. B. Bestellbestätigungen, Rechnungen und Gutschriften):

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

Bei Anfragen mit API-Key gilt die IP-Allowlist Ihres Accounts. Die API-Keys erscheinen auf jeder JSON-Pipeline in der Liste der Credentials, verwaltet werden sie zentral unter **API-Keys**.

### Authentifizierung ist Pflicht

Jede Anfrage muss sich mit einer aktiven Credential der Pipeline oder einem API-Key ausweisen. Eine Pipeline ohne Credential nimmt nur Anfragen mit API-Key an; gibt es auch keinen API-Key, weist der Webhook jede Anfrage mit **401** ab. Die Pipeline-Seite zeigt dann den Hinweis „Webhook nimmt nichts an".

## 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 (cXML, openTRANS, eigenes XML) – passend zum Eingangsformat der Pipeline |

Der Content-Type muss zum Eingangsformat der Pipeline passen – JSON an eine cXML-Pipeline lehnt
Orderport mit **406** ab, statt eine Nachricht anzunehmen, die später scheitern würde.

**Antwortformat:** Nur cXML-Dokumente bekommen eine cXML-Response. Alle anderen Formate – JSON,
EDIFACT, openTRANS, eigenes XML – bekommen JSON mit dem **echten HTTP-Status** (z. B. 401, 406,
409), damit Ihr System einen Fehler auch als Fehler erkennt.

## Antwort bei Erfolg

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

{
  "message_id": 456,
  "status": "queued",
  "pipeline_id": 12
}
```

Die Bestellung wurde empfangen und wird asynchron verarbeitet.

## Fehlerfälle

| HTTP-Status | Bedeutung |
|---|---|
| 401 Unauthorized | Ungültige oder fehlende Authentifizierung, oder ungültiger Pipeline-Token |
| 403 Forbidden | Pipeline inaktiv, oder API-Key von einer IP außerhalb der IP-Allowlist |
| 406 Not Acceptable | Ungültiger Content-Type |
| 400 Bad Request | Beleg-Pipeline: Der Body ist kein gültiges JSON-Objekt |
| 409 Conflict | Duplikat – Bestellung bzw. Beleg mit dieser Nummer wurde bereits empfangen |
| 413 Payload Too Large | Payload größer als 5 MB |
| 422 Unprocessable | Leerer Payload, oder ein Beleg entspricht nicht seinem Schema (siehe unten) |

## Belege senden

Bei Pipelines für Bestellbestätigungen, Rechnungen oder Gutschriften erwartet der
Webhook das feste **Orderport-JSON-Format** — Felder, Pflichtangaben und Beispiele
je Belegtyp finden Sie in der [API-Referenz](/docs/api-reference) und unter
[Belegausgang](/docs/belegausgang). Der Belegtyp ergibt sich aus der Pipeline.

Orderport prüft den Beleg beim Empfang. Ist er unvollständig, antwortet der
Webhook mit **422** und listet jedes fehlerhafte Feld; es wird keine Nachricht
angelegt:

```json
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
  "error": "validation_failed",
  "status": "error",
  "message": "Der Payload ist keine gültige Rechnung im Orderport-JSON-Format.",
  "errors": {
    "document_number": ["…"],
    "items.0.quantity": ["…"]
  }
}
```

Bestellungen werden nicht gegen ein Schema geprüft.

## 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**:

```json
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**:

```xml
<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/webhook/{token}` | `/api/v1/webhook/{token}` |
| Content-Type | `application/xml`, `text/xml` | `application/json` |
| 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

- [Integrationen-Übersicht](/docs/kategorie/integrationen) – Shopware 6, Shopify, WooCommerce und mehr
- [API-Zugang](/docs/api-zugang) – Bestellungen per API-Key senden
- [Bestellungen verwalten](/docs/bestellungen) – eingegangene Bestellungen einsehen
- [Zugangsdaten](/docs/credentials) – Auth-Typen im Detail
