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 -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
| Header | Meaning |
|---|---|
webhook-id | Event id (vevt_). Deduplicate on this value. |
webhook-timestamp | Unix timestamp (seconds) of the attempt. |
webhook-signature | v1,<base64 hmac-sha256> over id.timestamp.body. |
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.createdpayment.requires_actionpayment.processingpayment.requires_capturepayment.succeededpayment.failedpayment.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.
vevt_ id.