Webhooks

Create a webhook endpoint

The response contains secret — the HMAC signing key — and it is the only time it is ever returned. Store it now.

post/api/v1/customer/webhooks

Request

  • Base URL: https://virtualsms.io
  • URL: https://virtualsms.io/api/v1/customer/webhooks
  • Auth: one of:
    • API key in header X-API-Key
    • API key in query parameter api_key

Request body

urlstring uri required

Destination URL. Must be https:// — plain http, localhost and IP literals are rejected with 400.

descriptionstring nullable

Free-text label shown in your dashboard.

eventsstring[] required

Non-empty subset of the supported event types. Duplicates are collapsed.

thresholdnumber float nullable

Balance in USD below which balance.low fires. Required when events contains balance.low; must be > 0 and <= 99999.99. Ignored (stored as null) otherwise.

Example request

{
  "url": "https://your-server.com/virtualsms-events",
  "description": "production events",
  "events": [
    "sms.received",
    "order.expired"
  ],
  "threshold": 5
}

Response

Created — this response carries the secret

successboolean

Example response

{
  "webhook": {
    "id": "7",
    "url": "https://your-server.com/virtualsms-events",
    "description": "production events",
    "events": [
      "sms.received",
      "order.expired"
    ],
    "active": true,
    "threshold": 5,
    "last_error_code": "500",
    "secret": "whsec_a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.