Webhooks

Anstelle von Abfragen können Sie die Ereignisse einer Bestellung über Ihren HTTPS-Endpunkt empfangen. Webhooks übertragen dieselben Ereignisse wie Reihenfolge der Ereignisse. Das Ereignisprotokoll bleibt sowohl mit als auch ohne Webhooks verfügbar, sodass Sie jederzeit auf das Polling zurückgreifen können.

Einrichten

Bestanden callback_url in Auftrag erteilenoder legen Sie sie später fest mit Reihenfolge der Aktualisierungen.
Die Antwort lautet webhook_secret (whsec_…) einmal. Speichere es: Es signiert jeden Webhook.
Änderungen callback_url gibt ein neues Geheimnis aus. Das vorherige Geheimnis signiert Webhooks weiterhin 24 Stunden lang: Während dieser Zeit X-PS-Signature trägt zwei Signaturen.

Anfrage

Eigenschaft	Wert
Vorgehensweise	`POST` zu `callback_url`
Überschriften	`Content-Type: application/json; charset=utf-8`, `User-Agent: ProxySeller-Webhooks/1`, `X-PS-Timestamp`, `X-PS-Signature`
Haupttext	Ein Ereignis, wie in Reihenfolge der Ereignisse; `attempt` ist die Nummer des Zustellversuchs (1, 2, …)
Erfolg	Beliebige `2xx` innerhalb von 5 Sekunden. Weiterleitungen werden nicht verfolgt, der Antworttext wird nicht gelesen
Lieferung	Mindestens einmal, in beliebiger Reihenfolge. Duplikate entfernen durch `event_id`

POST /hooks/proxy HTTP/1.1
Host: agent.example.com
Content-Type: application/json; charset=utf-8
User-Agent: ProxySeller-Webhooks/1
X-PS-Timestamp: 1762077838
X-PS-Signature: v1=5f0c2a…9e

{"event_id":"evt_01JZ8QA2C4E6G8J0K2M4P6R8T0","type":"order.active","created_at":"2026-11-02T10:03:58Z","api_version":"v1","order_id":"ord_01JZ8Q7K5N2R4T6V8X0Z2B4D6F","wallet":"0x857b06519e91e3a54538791bdbb0e22373e36b66","attempt":1,"data":{"lines":[{"line_id":"1","status":"active","delivered":2,"qty":2}],"expires_at":"2026-12-02T23:59:59Z"}}

Signatur überprüfen

X-PS-Signature: v1=hex(HMAC-SHA256(key, timestamp + "." + raw_body))

key — die Bytes (UTF-8) des gesamten Textes webhook_secret Zeichenkette, einschließlich der whsec_ Präfix.
timestamp — der Wert von X-PS-Timestamp, Unix-Sekunden.
raw_body — der Textkörper genau so, wie er empfangen wurde, vor jeglicher JSON-Auswertung.
In den 24 Stunden nach einer geheimen Änderung lautet die Überschrift v1=<current>,v1=<previous>: Akzeptieren Sie die Anfrage, wenn eine der Angaben übereinstimmt.
Lehnen Sie Anfragen ab, deren Zeitstempel um mehr als 300 Sekunden von Ihrer Uhrzeit abweicht.

Python

import hashlib
import hmac
import time

def verify(secret: str, timestamp: str, signature_header: str, raw_body: bytes, tolerance: int = 300) -> bool:
    if abs(time.time() - int(timestamp)) > tolerance:
        return False
    expected = hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    candidates = [part.strip()[3:] for part in signature_header.split(",") if part.strip().startswith("v1=")]
    return any(hmac.compare_digest(expected, candidate) for candidate in candidates)

Node.js

import crypto from 'node:crypto';

function verify(secret, timestamp, signatureHeader, rawBody, toleranceSeconds = 300) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${timestamp}.`).update(rawBody).digest('hex');
  return signatureHeader.split(',').map((s) => s.trim()).filter((s) => s.startsWith('v1='))
    .some((s) => s.length === expected.length + 3
      && crypto.timingSafeEqual(Buffer.from(s.slice(3)), Buffer.from(expected)));
}

Wiederholversuche

Regel	Wert
Erster Versuch	Frühestens 30 Sekunden nach dem Ereignis
Wiederholversuche	Nach 1 Min., 5 Min., 30 Min., 2 Std., 6 Std., 12 Std. und 24 Std.: 8 Versuche in etwa 44,6 Stunden
Zu alt	Ein Ereignis, das älter als etwa 45,6 Stunden ist, wird nicht mehr gesendet.
Leistungsschalter	Nach drei Fehlversuchen in Folge warten die weiteren Ereignisse der Abfolge auf den nächsten Versuch.
Deaktivieren	Wenn der letzte Versuch eines Ereignisses fehlschlägt und die URL seit der Erstellung dieses Ereignisses keinen Webhook mehr akzeptiert hat, wird die Zustellung an die URL deaktiviert. Der Auftrag selbst ist davon nicht betroffen.

Um eine deaktivierte URL zu aktivieren, senden Sie sie erneut mit Reihenfolge der Aktualisierungen: dieselbe URL höchstens einmal pro Stunde, eine neue URL jederzeit. Verpasste Ereignisse stehen immer unter Reihenfolge der Ereignisse.

Regeln für die callback_url

Wird bei Erstellung des Angebots und in PATCH. Ein Verstoß führt zu 400 invalid_request:

Regel	Detail
Druckbares ASCII, bis zu 2048 Zeichen	`/callback_url: must be a printable URL up to 2048 characters`
`https` nur	`/callback_url: only https is allowed`
Keine Anmeldedaten oder Passwörter in der URL	`/callback_url: credentials in URL are not allowed`
Kein Fragment	`/callback_url: fragment is not allowed`
Nur Port 443	`/callback_url: only port 443 is allowed`
Ein öffentlicher DNS-Name oder eine kanonische IPv4-Adresse oder eine IPv6-Adresse in Klammern	`/callback_url: host must be a public DNS name`, `/callback_url: IPv4 address must be a canonical dotted quad`
Alle Adressen des Hosts sind öffentlich	`/callback_url: host resolves to a private or reserved address`, `/callback_url: host does not resolve`
Nicht der Betreiber des Dienstes selbst	`/callback_url: host is not allowed`

Vor jeder Zustellung wird die DNS erneut überprüft; die Anfrage geht nur an die geprüften Adressen.

Einrichten

Anfrage

Signatur überprüfen

Wiederholversuche

Regeln für die callback_url

On this page