Webhooks

Vellaro can notify your backend whenever something happens in your store (order created, paid, shipped, product changed), so you can keep ERPs, back-office systems, or external pipelines in sync without polling.

How it works

You register one or more endpoints from the admin panel or with the Admin API (POST /admin/webhooks, system permission), choosing the events.
Vellaro sends a POST to your URL on every subscribed event, with a JSON payload describing the event and the resource.
The request is signed: verify the signature with your secret before trusting the content.
Respond with 2xx within 10 seconds to acknowledge receipt; failed deliveries are retried.

curl -X POST "$BASE/api/v1/admin/webhooks" -H "Authorization: Bearer $STAFF" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://erp.example.com/hooks/vellaro","events":["order.paid","order.shipped"]}'

The response contains the signing secret (whsec_...), shown only once: store it right away. Later reads only show secret_last_four.

URL rules

The URL must be https to a public host, with no credentials in the URL. The check runs on save (with a DNS lookup) and again on every delivery:

`error_code` (422)	When
`webhooks.url_https_required`	the URL doesn’t start with `https://`
`webhooks.url_not_public`	the host is an internal network address or name (private IPs, `localhost`, names without a domain, hosts resolving to internal networks)
`webhooks.url_invalid`	URL empty, malformed, with credentials, or with an invalid port

A delivery to a destination that meanwhile resolves to an internal network ends as failed, with no further attempts. Redirects are not followed: a 3xx counts as a failure.

Events

GET /admin/webhooks/events returns the list of events you can subscribe to:

Event	When
`order.created`	new order from the checkout
`order.paid`	payment collected (gateway, gift voucher, or payment recorded by hand)
`order.shipped`	the order moves to “shipped”
`order.refunded`	total or partial refund, also through the “Refunded” status: the money goes back to the customer. `payment_status` and `amount_refunded` say how much
`product.created`	product created, also from a CSV import
`product.updated`	product updated, also from a CSV import
`product.deleted`	product deleted

Test deliveries carry the webhook.test event, which can’t be subscribed to.

Payload

{
  "event": "order.paid",
  "occurred_at": "2026-10-10T09:31:12.402117+00:00",
  "tenant_id": "7f3e9a1b-4c2d-4e5f-8a9b-0c1d2e3f4a5b",
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "processing",
    "payment_status": "paid",
    "payment_method": "stripe",
    "subtotal": "1199.00",
    "shipping_cost": "0.00",
    "total": "1079.10",
    "amount_refunded": "0.00",
    "currency": "EUR",
    "customer_email": "mario.rossi@example.com",
    "tracking_number": null,
    "created_at": "2026-10-10T09:30:00+00:00"
  }
}

For product.* events, data contains id, name, slug, and is_active. For the full detail, read the resource again with the Admin API.

Verifying the signature

Every request carries these headers:

Header	Content
`X-Vellaro-Event`	the event name
`X-Vellaro-Delivery`	the delivery id (the same across all attempts of the same delivery)
`X-Vellaro-Timestamp`	Unix seconds of the attempt
`X-Vellaro-Signature`	`sha256=` followed by the hex HMAC-SHA256 of `<timestamp>.` plus the raw body, with your secret

Compute the signature over the received bytes, not over re-serialized JSON, compare it in constant time, and reject timestamps that are too old.

import crypto from "node:crypto";

// rawBody: Buffer with the exact request body
export function verifyVellaro(rawBody, headers, secret) {
  const ts = headers["x-vellaro-timestamp"] ?? "";
  const sig = headers["x-vellaro-signature"] ?? "";
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(`${ts}.`).update(rawBody).digest("hex");
  const a = Buffer.from(sig);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

import hashlib
import hmac
import time

def verify_vellaro(raw_body: bytes, headers, secret: str) -> bool:
    ts = headers.get("X-Vellaro-Timestamp", "")
    sig = headers.get("X-Vellaro-Signature", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        return False
    mac = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256)
    return hmac.compare_digest(sig, "sha256=" + mac.hexdigest())

Retries and idempotency

Any response other than 2xx (redirects included), a timeout, or a network error is a failed attempt. The delivery is retried with growing waits (1, 2, 4, 8, and 16 minutes).
Attempts of the same delivery share the same X-Vellaro-Delivery. A manual redelivery instead creates a new delivery with the same payload: make your processing idempotent (for example on event, data.id, and occurred_at).
Answer 2xx right away and do the heavy work in a queue.

Management tools

All routes live under /admin/webhooks/{id} (system permission); a webhook of another store answers 404.

Route	What it does
`POST /admin/webhooks/{id}/test`	sends a signed `webhook.test` event right away, one attempt, even to a paused webhook. Answers `ok`, `duration_ms`, and the recorded delivery
`GET /admin/webhooks/{id}/deliveries`	delivery log, newest first, paginated and filterable with `status=pending`, `success`, or `failed`
`POST /admin/webhooks/{id}/deliveries/{delivery_id}/redeliver`	sends that event again as a new delivery: 202 with the `pending` delivery. On a paused webhook 409 `webhooks.inactive`; unknown delivery 404 `webhooks.delivery_not_found`
`POST /admin/webhooks/{id}/rotate-secret`	generates a new secret, shown only once
`PATCH /admin/webhooks/{id}`	changes `url`, `events`, or `is_active` (a `null` field stays unchanged)

Each delivery in the log has event_type, status, attempt, response_status, next_retry_at, delivered_at, and response_body: a safe excerpt of your endpoint’s response (at most 256 printable characters), enough to recognize the error.

After rotate-secret signatures use the new secret immediately and the old one stops verifying. Get your endpoint ready to accept both secrets, rotate, then remove the old one.

Webhooks are not needed for delivering digital products: after payment, the API issues signed download links, documented in the API Reference.

Get started

Guides

AI & MCP

How it works

URL rules

Events

Payload

Verifying the signature

Retries and idempotency

Management tools