Webhooks Overview

What are Webhooks?

Webhooks are HTTP callbacks that CloudVNO sends to your server when events occur — a message is delivered, a call is answered, a verification succeeds.

Instead of polling the API, webhooks push data to you in real time.

How Webhooks Work

1. You configure a publicly accessible HTTPS URL on your CloudVNO resource
2. An event occurs (e.g., SMS delivered)
3. CloudVNO sends an HTTP POST to your URL with event data
4. Your server processes the data and responds with HTTP 200
5. If your server is unavailable, CloudVNO retries up to 3 times

Webhook Events

Event	When it fires
Message delivered	Carrier confirms delivery
Message failed	Delivery failure
Message received	Inbound SMS/MMS
Call answered	Call connects
Call completed	Call ends (includes duration, price)
Call failed	Call not connected
Verification approved	OTP checked successfully
Number provisioned	Number activated in your account
Recording available	Call recording ready for download

Securing Webhooks

Always validate that incoming webhooks are genuinely from CloudVNO using the X-CloudVNO-Signature header.

import hmac
import hashlib
from urllib.parse import urlencode

def validate_cloudvno_signature(auth_token, signature, url, params):
    # Sort params and create validation string
    s = url + urlencode(sorted(params.items()))

    # Compute expected signature
    expected = hmac.new(
        auth_token.encode("utf-8"),
        s.encode("utf-8"),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected, signature)

Retry Logic

If your endpoint returns a non-2xx response or times out (> 10 seconds), CloudVNO retries:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes

After 3 failed retries, the webhook is marked as failed. Check your Dashboard → Webhook Logs for failed deliveries.

Local Development

Use a tool like ngrok to expose your local server:

ngrok http 3000
# Forwarding: https://abc123.ngrok.io → http://localhost:3000

Set https://abc123.ngrok.io/webhook as your webhook URL while developing.