Webhooks

The envelope

Every delivery has the same outer shape. The event you subscribed to is nested under event, and the two timestamps are different: one is when the event happened, the other is when this delivery attempt was made.

{
  "event": {
    "id": "d1ae5039-4640-4c9f-9e49-e2ee545cde2f",
    "type": "storefront.search_empty",
    "data": { /* shape depends on type */ },
    "timestamp": "2026-09-16T10:04:11.201Z"
  },
  "webhook_id": "cmu0acdx100klxgqvb5iobs1m",
  "timestamp": "2026-09-16T10:04:11.884Z"
}

Headers

Verifying a delivery

Compute HMAC-SHA256 over the raw request body, prefix it, and compare in constant time. Parsing the body to JSON and re-serialising it will change the bytes and the signature will not match.

import crypto from "node:crypto";

export function verify(rawBody, signatureHeader, secret) {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody).digest("hex");

  const a = Buffer.from(signatureHeader ?? "", "utf8");
  const b = Buffer.from(expected, "utf8");
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(a, b);
}

// In an Express handler, take the raw body before any JSON parser:
//   app.post("/webhooks/cresva", express.raw({ type: "application/json" }), (req, res) => {
//     const ok = verify(req.body, req.get("X-Cresva-Signature"), process.env.CRESVA_WEBHOOK_SECRET);
//     if (!ok) return res.status(401).send("bad signature");
//     res.sendStatus(200);
//   });

import hmac, hashlib

def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature_header or "", expected)

# In Flask, request.data is the raw body:
#   ok = verify(request.data, request.headers.get("X-Cresva-Signature"), SECRET)

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
)

func Verify(rawBody []byte, signatureHeader, secret string) bool {
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write(rawBody)
	expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
	return hmac.Equal([]byte(signatureHeader), []byte(expected))
}

Retries

A delivery that does not get a 2xx is retried 5 times, at 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours after the first attempt. After the last one it stops.

Return 200 as soon as you have stored the delivery, and do your work afterwards. A handler that does its processing before replying will be retried while it is still working, and you will process the same event twice.

Deduplicate on X-Cresva-Delivery-Id. It is unique per attempt, so an event redelivered after a timeout carries a different one; if you need to deduplicate on the event itself, use event.id from the body.

Two things the sender will not do

It does not follow redirects. A 301 or 302 from your endpoint is a failed delivery, not a hop. Register the final URL.

It will not deliver to a private address. The URL is re-validated against public-address rules immediately before each request rather than only when you save it, because DNS can change in between. A signed payload leaves only after that check passes.

The 36 event types

Subscribe to the ones you need, or to * for all of them. An endpoint receives only the types it is subscribed to.

Registering an endpoint

Endpoints are registered from the Cresva dashboard, under the storefront settings for a brand. There is no public endpoint for managing them, and this page does not document one: an earlier version of it showed management cURL examples for routes that are not exposed.