Webhooks
Bestell-Ereignisse an eigene Tools senden - signiert, wiederholt, dedupliziert
Für alles, wofür vendael keinen nativen Connector hat: registrieren Sie einen HTTPS-Endpunkt und erhalten Sie jedes Bestell-Ereignis als signierten JSON-Push.
Einrichtung
Integrationen → Webhook - benennen und Endpunkt-URL eintragen. Das Signatur-Secret wird genau einmal bei der Erstellung angezeigt; bewahren Sie es sicher auf.
Zustellung
Jedes Ereignis ist ein POST mit JSON-Body (Ereignisname und
Bestell-Snapshot) sowie diesen Headern:
| Header | Inhalt |
|---|---|
X-Vendael-Event | Ereignisname (z. B. Bestellstatus) |
X-Vendael-Delivery-Id | eindeutige ID - zum Deduplizieren nutzen |
X-Vendael-Timestamp | Unix-Zeitstempel der Zustellung |
X-Vendael-Signature | HMAC-Signatur (siehe unten) |
Antworten Sie mit einem beliebigen 2xx innerhalb von 15 Sekunden. Fehlschläge werden bis zu 8-mal mit exponentiellem Backoff wiederholt; Wiederholungen tragen dieselbe Delivery-ID.
Signatur prüfen
X-Vendael-Signature = hex( HMAC-SHA256( secret, timestamp + "." + rawBody ) )
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(req, rawBody, secret) {
const expected = createHmac("sha256", secret)
.update(`${req.headers["x-vendael-timestamp"]}.${rawBody}`)
.digest("hex");
const given = req.headers["x-vendael-signature"] ?? "";
return (
given.length === expected.length &&
timingSafeEqual(Buffer.from(given), Buffer.from(expected))
);
}Lehnen Sie alles ab, was die Prüfung nicht besteht, und erwägen Sie, Zeitstempel älter als wenige Minuten zurückzuweisen, um Replays zu verhindern.
Authentifizierungs-Optionen
X-Vendael-Signature mit dem Schema oben ist der Standard. Unter
Authentifizierung in der Endpunkt-Zeile passen Sie es an das an, was Ihr
Empfänger unterstützt:
| Methode | Einstellungen | Typischer Empfänger |
|---|---|---|
| HMAC-Signatur | Header-Name, signierter Inhalt (Zeitstempel + "." + Body oder nur roher Body), Kodierung (hex / base64) | eigener Code, generische X-Signature-Empfänger wie Shopify Flow |
| Statisches Token | Header-Name, Präfix (z. B. Bearer ), Token (eigenes oder erzeugt) | Tools, die nur einen API-Key vergleichen (Authorization, X-Api-Key) |
| Keine | – | Endpunkte, die per Allow-List oder nicht erratbarer URL geschützt sind |
Beispiel für einen generischen Empfänger: Methode HMAC-Signatur, Header
X-Signature, signierter Inhalt nur roher Body, Kodierung base64 → der
Header entspricht base64( HMAC-SHA256( secret, rawBody ) ). Ein neues
Signatur-Secret oder ein erzeugtes Token wird einmal angezeigt.
Testen
Der Test-Button an der Endpunkt-Zeile sendet ein signiertes Test-Ereignis, mit dem Sie Ihre Implementierung Ende-zu-Ende prüfen können.