Produktdaten per Webhook in PassportLab übertragen

1. Einrichtung

1. Gehen Sie im PassportLab-Dashboard zu Integrationen.
2. Klicken Sie auf der Kachel Generic Webhook auf Webhook konfigurieren.
3. Geben Sie der Integration eine Bezeichnung (z. B. SAP S/4HANA Produktion).
4. Bei der Erstellung zeigt ein einmaliger Dialog die Webhook-URL und das Signaturgeheimnis. Kopieren Sie beides sofort — das Geheimnis wird nur einmal angezeigt.
5. (Optional, aber empfohlen.) Öffnen Sie Zuordnungsregeln auf der Integrationskarte und ordnen Sie die Feldnamen Ihres ERP den DPP-Passdatenfeldern zu. Die integrierte Test-Schaltfläche zeigt die normalisierte Ausgabe anhand einer Beispiel-Nutzlast.

3. Signierung

Wir verwenden das Signaturschema im Stripe-Stil: Zeitstempel + Punkt + Body, HMAC-SHA256, Hex-Digest, vorangestellt mit sha256=.

signing_base = <timestamp> + "." + <raw request body bytes>
signature    = "sha256=" + HMAC-SHA256(secret, signing_base).hexdigest()

Die Einbeziehung des Zeitstempels in die signierte Nutzlast ist ein Replay-Schutz: Selbst wenn eine gültige Anfrage durchsickert, kann sie außerhalb des 5-Minuten-Fensters nicht erneut gesendet werden.

import hashlib, hmac, json, time, requests

INTEGRATION_ID = "REPLACE_ME"
SECRET         = "REPLACE_ME"  # from your credential vault
BASE_URL       = "https://api.passportlab.io"

records = [{"name": "Widget Pro", "barcode": "01234567890123"}]
body    = json.dumps({"records": records}).encode("utf-8")
ts      = str(int(time.time()))
sig     = "sha256=" + hmac.new(
    SECRET.encode(), f"{ts}.".encode() + body, hashlib.sha256
).hexdigest()

res = requests.post(
    f"{BASE_URL}/api/v1/integrations/{INTEGRATION_ID}/webhook-ingest",
    data=body,
    headers={
        "Content-Type": "application/json",
        "X-PassportLab-Timestamp": ts,
        "X-PassportLab-Signature": sig,
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())  # → {"jobId": "...", "totalRecords": 1, "enqueued": true}

5. Feldzuordnung

Wenn die Nutzlaststruktur Ihres ERP vom DPP-Schema abweicht (was fast immer der Fall ist), definieren Sie Zuordnungsregeln im Dashboard. Jede Regel besteht aus vier Feldern:

7. Betriebshinweise

Idempotenz

PassportLab verwendet den DPP-Code (abgeleitet aus GTIN + Seriennummer) als eindeutige Kennung. Das erneute Senden eines Datensatzes mit derselben GTIN+Seriennummer wird übersprungen, nicht dupliziert — die Antwort markiert ihn als skipped mit dem Grund "DPP code 'DPP-…' already exists". Bei vorübergehenden Fehlern gefahrlos wiederholbar.

Wiederholungen

Bei 502 / 503 / 504 oder Netzwerk-Timeouts mit exponentiellem Backoff erneut versuchen (1s, 2s, 4s, 8s, gedeckelt bei 30s). In der Regel reichen bis zu 3 Wiederholungen. Nicht bei 4xx-Antworten wiederholen — die Anfrage schlägt erneut fehl.

Batching

• Kleine ERPs (< 1 000 SKUs): den vollständigen Katalog nächtlich in einem Aufruf senden.
• Größere ERPs: nur das Delta senden (seit der letzten Synchronisierung geänderte Zeilen), in Gruppen von bis zu 1 000 Datensätzen pro Anfrage.