Receive webhook subscription events

After you create a webhook subscription, Vitesse delivers events to your configured endpoint whenever the subscribed event types occur.

Vitesse sends a POST request to your HTTPS endpoint with a JSON payload containing the event details.

Endpoint requirements

Your endpoint must:

• Be publicly accessible over HTTPS
• Support TLS 1.2 or TLS 1.3
• Accept POST requests with application/json content
• Return a 2xx status code within 5 seconds
• Handle retries and duplicate deliveries

If your endpoint does not return a 2xx response within 5 seconds, Vitesse retries delivery according to the retry policy.

Verify webhook subscription authenticity

Your endpoint must verify the authenticity of each incoming webhook subscription request.

HMAC signature verification (recommended)

Vitesse signs each payload using HMAC-SHA256 and includes the signature in the Vitesse-Signature header.

Signature format:

timestamp=<timestamp>,v1=<signature>[,v2=<rotated-secret-signature>]

Verify the signature:

1. Concatenate timestamp.payload.
2. Compute the HMAC using your shared secret.
3. Compare the result with v1 (and optionally v2 during key rotation).

Basic authentication

If configured, Vitesse includes credentials in the Authorization: Basic header. Validate these credentials before processing the event.

Event delivery format

Each webhook delivery contains an Event object. See Event Reference for the full structure.

Idempotency

Vitesse delivers webhook events using an at-least-once model and may deliver the same event more than once.

Use the EventId field as a deduplication ID to ensure your system processes each event only once.

Event ordering

Webhook events are delivered asynchronously:

• Delivery order is not guaranteed
• Each subscription endpoint receives events independently

💡

Design your system to tolerate out-of-order delivery, and reconcile state periodically using system-of-record APIs.

Retry behaviour

If your endpoint does not return a 2xx response, Vitesse retries delivery using exponential backoff with jitter.

Retries continue until the retry limit is reached, or the subscription is disabled or deleted.

Monitor delivery attempts and investigate repeated failures using the Webhook Management API. For more information, see Manage webhook subscriptions.

💡

Reject events older than 5 minutes to mitigate replay attacks.

Test your integration

Before going live:

• Trigger a test payment
• Confirm your endpoint returns 2xx within 5 seconds
• Verify HMAC signatures (if enabled)
• Confirm duplicate deliveries are handled correctly using the EventId field