Create event subscription

Creates a subscription that sends events of one model to your post-url as they happen. Create one subscription per model.

Requires Basic User, Site Manager, Office Manager, Reseller, or Super User, and read access to the model you name. Without it you get 403. An unknown model returns 400.

What you can subscribe to depends on your scope:

Super User: any domain, or * for every domain on the platform

Reseller: one domain in its own territory, for one user or * for all

Office Manager: its own domain, for one user or * for all

Site Manager: users of its own site in its own domain, never *

Basic User: its own extension

A platform-wide subscription (domain *) from any other scope returns 403, and a domain that does not exist returns 404. The territory is taken from the domain.

Choose model from these values:

`model`	Sends
`call`	Active call updates
`call_origid`	Active call updates, only the latest state of each call per batch
`cdr`	Completed call records
`agent`	Call center agent status changes, matched on the call queue
`voicemail`	New voicemail
`message`, `messagesession`	Chat and SMS messages and sessions

Also available: presence, subscriber, auditlog, auditlog_lite (creates and deletes of main objects only), domain, and device. presense is a misspelt presence model that is still accepted.

Events are matched on domain and user only. * matches every value.

post-url must be an http:// or https:// URL with a host, at most 256 characters, with the scheme only once and no user:password@ part. Unless you are a Super User, every address the host resolves to must be public: loopback, link-local, private, shared (CGNAT), and unique-local addresses are refused, and so are this platform's own servers. A host that does not resolve is refused too. Each refusal is a 400 that names the rule. An installation can allow private addresses with the NsSubscriptionAllowPrivateUrls setting. Use https:// with a certificate that validates, because a certificate error counts as a failed delivery.

subscription-expires-datetime takes RFC 3339, such as 2027-09-01T14:30:00+00:00, or YYYY-MM-DD HH:MM:SS in UTC. It is stored in UTC and read back as RFC 3339. Any other value returns 400.

The id is derived from the model, scope, territory, domain, user, post-url, and subscription-geo-support, so creating the same subscription twice returns 409. The call waits up to 5 seconds for the new subscription to be stored and then returns it with 200. Delivery starts within about 5 seconds after that.

Delivery: every 500 milliseconds, the server that owns the subscription sends one POST to post-url with a JSON array of every event queued since the last send. The request carries Content-Type: application/json; charset=utf-8 and X-Correlation-ID set to the subscription id, and no credentials or signature. The events are the platform's own records, with their internal field names, not the v2 names. A response above 302, a connection failure, or no answer within 15 seconds counts as an error. A failed batch is not retried and its events are lost, so reconcile gaps with the matching read endpoint. Redirects are not followed, and a 301 or 302 counts as delivered. Repeated failures never disable a subscription: it keeps sending until it expires or you delete it. Retries and a signing secret are tracked in NN-663.

Watch status and error-count to see whether delivery works. Delivery stops at subscription-expires-datetime, and the subscription is deleted about 8 hours later. To keep it, send a later subscription-expires-datetime with PUT /subscriptions/{id} before then.

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

curl --location 'https://awqacore01.crexendocloud.com/ns-api/v2/subscriptions' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "post-url": "https://core1.example.com/log.php", "model": "call", "user": "*", "reseller": "*", "domain": "*", "user-scope": "Super User", "subscription-geo-support": "yes", "server_preferred": "core1.example.com" }'

{ "id": "9f86d081884c7d659a2feaa0c55ad015", "model": "call", "post-url": "https://webhook.example.com/events", "subscription-geo-support": "yes", "user-scope": "Reseller", "reseller": "example-reseller", "domain": "example.com", "user": "*", "subscription-creation-datetime": "2026-09-01T14:30:00+00:00", "subscription-expires-datetime": "2027-09-01T14:30:00+00:00", "preferred-server": "core1.example.com", "current-active-server": null, "status": "pending", "error-count": 0, "posts-count": 0 }

Request

Responses