Webhooks
Push order events to your own tools - signed, retried, deduplicated
For anything vendael doesn't have a native connector for: register an HTTPS endpoint and receive every order event as a signed JSON push.
Setup
Integrations → Webhook - name it and enter your endpoint URL. The signing secret is shown exactly once at creation; store it safely.
Delivery
Each event is a POST with a JSON body containing the event name and the
order snapshot, plus these headers:
| Header | Content |
|---|---|
X-Vendael-Event | event name (e.g. order state) |
X-Vendael-Delivery-Id | unique id - use it to deduplicate |
X-Vendael-Timestamp | Unix timestamp of the delivery |
X-Vendael-Signature | HMAC signature (see below) |
Answer with any 2xx within 15 seconds. Failures are retried up to 8 times with exponential backoff; retries carry the same delivery id.
Verifying the signature
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))
);
}Reject anything that fails verification, and consider rejecting timestamps older than a few minutes to prevent replays.
Authentication options
X-Vendael-Signature with the scheme above is the default. Under
Authentication on the endpoint row you can adapt it to what your receiver
supports:
| Method | Settings | Typical receiver |
|---|---|---|
| HMAC signature | header name, signed content (timestamp + "." + body or raw body only), encoding (hex / base64) | your own code, generic X-Signature receivers such as Shopify Flow |
| Static token | header name, prefix (e.g. Bearer ), token (yours or generated) | tools that only compare an API key (Authorization, X-Api-Key) |
| None | – | endpoints protected by an allow-list or an unguessable URL |
Example for a generic receiver: method HMAC signature, header X-Signature,
signed content raw body only, encoding base64 → the header equals
base64( HMAC-SHA256( secret, rawBody ) ). Rotating the signing secret or
generating a token shows the new value once.
Testing
The Test button on the endpoint row sends a signed test event so you can verify your implementation end-to-end.