Sandbox docs

Webhooks

Register HTTPS endpoints to receive Vestonix events. Payloads describe Vestonix resources only. The signing secret (vwhsec_) is shown once when the endpoint is created.

Register an endpoint

curl
curl -X POST "https://sandbox-api.vestonix.io/v1/webhook-endpoints" \
  -H "Authorization: Bearer vsk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/vestonix-webhooks",
    "enabled_events": [
      "payment.created",
      "payment.processing",
      "payment.succeeded",
      "payment.failed"
    ]
  }'

POST /v1/webhook-endpoints requires webhooks:write. Rotate the signing secret with the rotate-secret operation when you need to cut over verifiers.

Signature headers

HeaderMeaning
webhook-idEvent id (vevt_). Deduplicate on this value.
webhook-timestampUnix timestamp (seconds) of the attempt.
webhook-signaturev1,<base64 hmac-sha256> over id.timestamp.body.
Node.js
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyVestonixWebhook(input: {
  secret: string;
  id: string;
  timestamp: string;
  rawBody: string;
  signatureHeader: string;
}) {
  const key = Buffer.from(input.secret.replace(/^v?whsec_/, ""), "base64url");
  const expected = createHmac("sha256", key)
    .update(`${input.id}.${input.timestamp}.${input.rawBody}`, "utf8")
    .digest("base64");
  const provided = input.signatureHeader.split(" ").find((part) => part.startsWith("v1,"))?.slice(3);
  if (!provided) return false;
  const a = Buffer.from(provided, "base64");
  const b = Buffer.from(expected, "base64");
  return a.length === b.length && timingSafeEqual(a, b);
}

Reject deliveries whose timestamp is more than five minutes from your clock.

Payment events

  • payment.created
  • payment.requires_action
  • payment.processing
  • payment.requires_capture
  • payment.succeeded
  • payment.failed
  • payment.cancelled

Refund events also exist: refund.created, refund.processing, refund.succeeded, refund.failed. webhook.test is sent only when you trigger a test delivery.

Retries

Non-2xx responses and network failures retry with backoff, then stop: up to 7 attempts total, delays 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours, 24 hours. Client errors such as 400 are not retried. Deliveries are at-least-once — treat the event as a hint and retrieve the payment from the API before fulfilling.

Automatic retries depend on the Vestonix worker that processes the delivery queue. If a delivery stays pending, inspect it via the webhook delivery list or ask Vestonix support with the vevt_ id.