# 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

```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 Credential deaktiviert |
| 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**:

```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/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

- [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