Getting Started

To manage your webhooks:

1. Log in to VI Now.
2. Navigate to the Webhooks section.
3. Use the management interface to:
   1. Register endpoints to receive events
   2. Subscribe to specific event types
   3. View delivery logs

👤 An Admin must enable the Webhooks page in VI Now before users in the organization can access it.

Creating and Managing Endpoints

1. In the Webhooks section, click Add Endpoint.
2. Provide your endpoint URL and optional description.
3. Optionally add custom headers.
4. A signing secret will be generated for validating event signatures.

Subscribing to Events

You can subscribe to any combination of the following event types. This consolidated list reflects the order lifecycle, reward status updates, and payout events as used throughout the VI platform:

Viewing Logs

Navigate to the Logs tab within the Webhooks interface to:

• View webhook deliveries and retries
• Inspect request/response payloads
• Diagnose failed or delayed notifications

⏱️ Webhooks are retried automatically using exponential backoff.

📦Payload

Each webhook contains a JSON body with the following structure:

Example Webhook Payloads

{
  "date": "06/17/2025 16:01:56",
  "event": "reward.canceled",
  "event_id": "339133515",
  "note": "",
  "recipient_id": "42498355",
  "user": "John Smith"
  }
  
{
  "date": "06/17/2025 16:01:58",
  "event": "reward.credit_applied",
  "event_id": "339128032",
  "note": "$10.00",
  "recipient_id": "42498355",
  "user": "John Smith"
}

Payload Fields

🔐Webhook Signature Verification

Each webhook includes headers that allow you to verify the authenticity of the request using an HMAC-based signature.

Required Headers

How to Verify the Signature

1. Concatenate the three values: svix-id, svix-timestamp, and the raw request body with a period (.) as a separator:

to_sign = svix-id + "." + svix-timestamp + "." + raw_body

2. Compute the HMAC SHA256 digest of to_sign using your secret key (provided to you by VI), and encode it as a Base64 string:

import hmac
import hashlib
import base64

secret = base64.b64decode("your-secret-here")
signature = base64.b64encode(
    hmac.new(secret, to_sign.encode(), hashlib.sha256).digest()
).decode()

3. Compare this computed signature with the one in the svix-signature header. If they match, the webhook is authentic.

Additional Resources

Verifying webhook payloads - If you prefer to use a library rather than implement the verification logic manually, this guide provides examples in multiple languages and frameworks:

IP Addresses for Whitelisting - Optionally whitelist IP addresses from which webhook events will be delivered. The only applicable IPs for Virtual Incentives are listed under "US".

🔄 Retry Behavior

If your server does not respond with a 2xx HTTP status code, we will retry the webhook several times with exponential backoff.

Ensure your endpoint can safely handle duplicate events.

✅ Security Best Practices

• Respond quickly with a 200 OK after validating and logging the event.
• Always validate the svix-signature.
• Store the latest status for each uuid to maintain a full verification history.
• Secure your endpoint with HTTPS
• Limit IP access or implement token-based authentication where possible.
• Log and monitor webhook traffic for anomalies.