Webhooks

Webhooks are self-serve. Create, edit and delete them yourself with your API key — there is nothing to request and nobody to email. A webhook is an HTTPS URL we POST a signed JSON envelope to when something happens on your account. Use them instead of polling GET /api/v1/orders/{id} in a loop.

Base path: https://virtualsms.io/api/v1/customer/webhooks. Authenticate with the same x-api-key header as every other endpoint — including a key minted through the x402 top-up flow.

Event types

Exactly five event types exist. Subscribing to anything else is rejected with 400.

Event	Fires when
`sms.received`	An SMS arrives on one of your numbers
`order.cancelled`	An order is cancelled
`order.expired`	An order expires without an SMS
`order.swapped`	An order is renumbered via swap
`balance.low`	Your balance falls below the `threshold` you set

balance.low requires a threshold; the other four do not.

Create a webhook

curl -X POST https://virtualsms.io/api/v1/customer/webhooks \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/vsms-hook",
    "description": "prod SMS listener",
    "events": ["sms.received", "order.expired"]
  }'

{
  "success": true,
  "webhook": {
    "id": "3f2a91c4-8e5b-4d17-9a02-c1b6e7f45d80",
    "url": "https://your-server.com/vsms-hook",
    "description": "prod SMS listener",
    "events": ["sms.received", "order.expired"],
    "active": true,
    "paused": false,
    "threshold": null,
    "failure_count_consecutive": 0,
    "last_delivered_at": null,
    "last_error_at": null,
    "last_error_code": null,
    "created_at": "2026-09-07T12:00:00.000Z",
    "updated_at": "2026-09-07T12:00:00.000Z",
    "secret": "9f1c...<64 hex chars>"
  }
}

secret is returned exactly once, in this create response. Store it now — no other endpoint will ever return it, and there is no “show secret” call.

URL rules

The URL is validated on create and on update. It must:

use https:// — http:// and every other scheme are rejected
resolve to a public host — loopback, private and link-local hosts are rejected
be at most 2048 characters

Manage webhooks

Method	Path	Does
`GET`	`/api/v1/customer/webhooks`	List your webhooks (never includes secrets)
`POST`	`/api/v1/customer/webhooks`	Create one — returns the secret once
`GET`	`/api/v1/customer/webhooks/{id}`	Fetch one
`PATCH`	`/api/v1/customer/webhooks/{id}`	Update `url`, `description`, `events`, `threshold`, `active`, `paused`
`DELETE`	`/api/v1/customer/webhooks/{id}`	Delete permanently
`POST`	`/api/v1/customer/webhooks/{id}/test`	Fire a synthetic event through the real delivery path
`GET`	`/api/v1/customer/webhooks/{id}/deliveries`	Delivery history, newest first

GET list returns { "success": true, "webhooks": [...], "count": N }. DELETE returns { "success": true, "id": "3f2a91c4-8e5b-4d17-9a02-c1b6e7f45d80" }. PATCH accepts any subset of the updatable fields; sending none returns 400. Manually setting paused: false also resets the consecutive-failure counter to zero.

Test-fire

curl -X POST https://virtualsms.io/api/v1/customer/webhooks/3f2a91c4-8e5b-4d17-9a02-c1b6e7f45d80/test \
  -H "x-api-key: YOUR_API_KEY"

{
  "success": true,
  "message": "Test event queued — dispatcher will deliver within ~5 seconds",
  "delivery_id": "b8d40c2f-1a67-49e3-8f5c-70ad9e213b46",
  "event_id": "evt_01JB9K2M4Q7X0V3H8T6D5Z1PWR",
  "event_type": "sms.received"
}

The test event uses the first event type the endpoint is subscribed to. The endpoint must be active and not paused, or the call returns 400.

Delivery history

curl "https://virtualsms.io/api/v1/customer/webhooks/3f2a91c4-8e5b-4d17-9a02-c1b6e7f45d80/deliveries?limit=50" \
  -H "x-api-key: YOUR_API_KEY"

Returns { "success": true, "deliveries": [...], "count": N, "limit": 50, "offset": 0 }. Each delivery carries id, event_id, event_type, attempt, status, response_status, response_body, scheduled_for, delivered_at, error_message, created_at and the full payload that was sent. limit defaults to 100 and is capped at 500.

The envelope we POST

Every event — including the test event — has the same envelope shape:

{
  "id": "evt_01JB9K2M4Q7X0V3H8T6D5Z1PWR",
  "type": "sms.received",
  "created_at": "2026-09-07T12:00:00.000Z",
  "account_id": "a17c4e90-5b32-4f81-bd6e-2c9f018a37e4",
  "data": {}
}

id is a ULID-suffixed event id, unique per event and stable across retries — use it to deduplicate. The contents of data vary by event type.

Headers

Header	Value
`X-VirtualSMS-Signature`	`sha256=<hex>` — HMAC-SHA256 of the raw body, keyed by your secret
`X-VirtualSMS-Timestamp`	Milliseconds since epoch at send time
`X-VirtualSMS-Event`	The event type, e.g. `sms.received`
`X-VirtualSMS-Delivery`	Delivery id — same event retried keeps its own delivery row

Verifying the signature

Compute the HMAC over the raw request body bytes, before any JSON parsing, and compare in constant time.

import hmac, hashlib

def verify(secret: str, raw_body: bytes, signature_header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

const crypto = require('crypto');

function verify(secret, rawBody, signatureHeader) {
  const expected =
    'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(signatureHeader || '', 'utf8');
  const b = Buffer.from(expected, 'utf8');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Retries and auto-pause

Return any 2xx status to acknowledge. Anything else — including a timeout — is a failure.
Each request times out after 5 seconds.
Up to 5 attempts per event. Attempt 1 fires immediately; the gaps after a failed attempt are 1 minute, 5 minutes, 30 minutes, 2 hours. After the fifth failure the delivery is marked a permanent failure and is not retried.
A successful delivery resets your endpoint’s consecutive-failure counter to zero.
After 20 consecutive failures the endpoint is auto-paused and stops receiving events. Un-pause it with PATCH {"paused": false}, which also clears the counter.

Deliveries queued while an endpoint is inactive or paused are skipped rather than held.

Dashboard

Everything on this page is also available in the dashboard under Settings → Webhooks.

Getting Started

Integration

Earn

Event types

Create a webhook

URL rules

Manage webhooks

Test-fire

Delivery history

The envelope we POST

Headers

Verifying the signature

Retries and auto-pause

Dashboard

​Event types

​Create a webhook

​URL rules

​Manage webhooks

​Test-fire

​Delivery history

​The envelope we POST

​Headers

​Verifying the signature

​Retries and auto-pause

​Dashboard

Event types

Create a webhook

URL rules

Manage webhooks

Test-fire

Delivery history

The envelope we POST

Headers

Verifying the signature

Retries and auto-pause

Dashboard