Outbound webhooks

VICIfast can POST customer-lifecycle events to an HTTPS endpoint you control — useful for piping signups, orders, and server state changes into your CRM, billing system, or a notification rail. Every delivery is signed with HMAC-SHA256 so you can prove it came from us. This guide covers adding an endpoint, the events you can subscribe to, verifying signatures, and what happens when your endpoint is down.

Add an endpoint

1. Open Webhooks in your reseller dashboard (/dashboard/reseller/webhooks).
2. Under Add endpoint, paste your Endpoint URL — HTTPS only; plain HTTP is refused.
3. Optionally give it a Label (e.g., "CRM webhook") so you recognize it later.
4. Tick the events you want under Events — or leave every box unticked to receive all events.
5. Click Add endpoint.
6. Copy the signing secret from the confirmation banner and store it somewhere safe. It is shown ONCE — we hash and seal it right after and can never display it again.

The top of the page shows a 24-hour health rollup across your endpoints: Delivered, Retrying, and Exhausted counts. Each endpoint row has four actions: Test (queue a synthetic event), Pause / Resume (stop deliveries without losing the configuration), Deliveries (the per-endpoint log), and Delete. Deleting an endpoint also deletes its delivery history and drops any deliveries still waiting to be sent.

Events

The checklist offers these ten event types:

• CUSTOMER_SIGNED_UP — a new user signed up under your scope.
• ORDER_PAID — a paid order finalized. The payload includes the order id, the customer, the total, and your wholesale + margin breakdown.
• SERVER_PROVISIONED — a server transitioned to ACTIVE.
• SERVER_SUSPENDED — server moved to SUSPENDED (dunning, manual, or terminate cascade).
• SERVER_TERMINATED — server moved to TERMINATED.
• TRIAL_ISSUED — you issued a trial server.
• TICKET_OPENED — a customer opened a support ticket in your queue.
• AI_ANALYSIS_CHARGED — an AI recording analysis was billed under your scope (includes the retail / wholesale / margin breakdown).
• TTS_CHARGED — a text-to-speech generation was billed under your scope (same retail / wholesale / margin shape).
• DOMAIN_VERIFICATION_FAILED — the daily re-check of one of your white-label domains failed; fix it before certificates stop renewing.

One extra event exists outside the checklist: ORDER_CANCELED fires when you reject a manual-payment order. Endpoints subscribed to all events (empty checklist) receive it; you cannot subscribe to it selectively.

Signing and verification

Every POST carries three headers:

• X-Vicifast-Event — the event type.
• X-Vicifast-Signature — HMAC-SHA256 hex of the raw request body, keyed with your endpoint secret.
• X-Vicifast-Delivery — a unique delivery id; use it for idempotency on your side.

Verify in Node:

const sig = crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex');
if (sig !== req.headers['x-vicifast-signature']) return res.status(401).end();

Hash the raw body bytes exactly as received. If your framework parses JSON first (Express’s express.json(), for example), the re-serialized body will not match and every signature check fails — mount express.raw() on the webhook route instead.

Retries and timing

Respond with any 2xx within 10 seconds to acknowledge. Anything else — non-2xx, timeout, DNS or TLS failure — counts as a failed attempt. We retry up to 8 attempts with exponential backoff: 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours, 24 hours, 48 hours, 72 hours. After the 8th failure the delivery is marked EXHAUSTED and stops retrying; it stays visible in the delivery log and you can retry it manually from there.

One honest caveat: deliveries are sent by a worker that ticks once an hour (at :07 past the hour). The first attempt for an event can land up to about an hour after the event happened, and a scheduled retry fires on the first tick at or after its backoff time. Treat webhooks as eventual sync, not a real-time trigger.

Testing

Click Test on an endpoint row to queue a synthetic CUSTOMER_SIGNED_UP event with test: true in the payload. It goes out on the next worker tick — use it to verify your signature check end-to-end before going live. The Deliveries page then shows exactly what your endpoint answered.

Good to know

• Lost the signing secret? Delete the endpoint and add it again — the secret is sealed at creation and cannot be recovered. The new endpoint gets a fresh secret.
• URLs cannot be edited after creation. To change where events go, delete the endpoint and add a new one — and remember this wipes the old endpoint’s delivery history.
• Pausing an endpoint stops future sends. Queued deliveries the worker reaches while the endpoint is paused are marked exhausted with the error "endpoint disabled", so resume before their retries come due if you want them to fire.
• All deliveries are eventual, not instant — see the hourly tick note above. If you need something immediately, check the dashboard instead.