Create Webhook Subscription

Creates a new webhook subscription to receive push notifications when entity events occur.

How it works
Subscribe to events (add, update, delete) for any entity type (Users, Groups, Calls, Numbers, etc.). When the subscribed event occurs, a JSON payload is automatically sent to your webhook endpoint.

⚠️ Endpoint Validation
During creation, a test payload is sent to your endpoint URL to verify it is reachable. The endpoint must:

Use HTTPS protocol

Respond within 5 seconds

Return HTTP 2xx, 3xx, or 4xx status

If validation fails (5xx error, timeout, or network error), subscription creation is rejected with 400 Bad Request.

🔄 Automatic Retry & Disable
Failed webhook deliveries are automatically retried 3 times with exponential backoff. If all retries fail, the subscription is automatically disabled (status: inactive) and the account admin receives an email notification.

Required fields

subscription_name — Display name for this subscription

endpoint_url — Your HTTPS webhook URL where events will be sent

entity_type — Entity to subscribe to (Users, Groups, Calls, Numbers, Tags, etc.)

event_types — Array of events: ["add", "update", "delete"]

Optional fields

http_method — HTTP method for webhook delivery (default: POST)

custom_headers — Custom headers to include in webhook requests (e.g., API keys)

response_format — Response format: JSON or XML (default: JSON)

Supported Entities
Users, Groups, Campaigns, Provisioned Route, Calls, Numbers, Tags, CustomSource, VoiceAgents, Insights, Scorecard, Broadcast, DNI, Blacklist, Call Action, Media Prompts, Webhooks

Event Payload Example

{
  "key": "Users",
  "event_type": "update",
  "entity_id": 456,
  "org_unit_id": 123,
  "timestamp": "2026-05-25T10:30:00Z",
  "data": {
    "who_updated": {
      "id": 789,
      "name": "Admin User",
      "email": "admin@example.com"
    },
    "what_updated": [
      {
        "field_name": "user_status",
        "old_value": "active",
        "new_value": "inactive"
      }
    ],
    "entity_data": { ... }
  }
}

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location 'https://platform-api.convirza.com/v3/subscriptions' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "subscription_name": "User Activity Webhook", "endpoint_url": "https://customer.com/webhooks/users", "http_method": "POST", "custom_headers": [ { "header_name": "Authorization", "header_value": "Bearer sk_live_123456" } ], "entity_type": "Users", "event_types": [ "add", "update", "delete" ], "response_format": "JSON" }'

Create Webhook Subscription

Request

Responses