Event catalogue
Every event has the same envelope
{
"eventId": "01JB2K9WQ4X7YH3M8N5P6R7T8V",
"eventType": "subscription.created",
"occurredAt": "2026-09-10T14:32:07+00:00",
"shortCode": "2761",
"serviceId": 4821,
"msisdn": "9647500000000",
"…": "event-specific fields"
}
| Field | Notes |
|---|---|
eventId | Your deduplication key. |
eventType | One of the events below. |
occurredAt | ISO 8601, when it happened rather than when it was delivered. |
shortCode | The short code the destination is registered against. |
serviceId | An integer, and it identifies which of your services the event is about. |
msisdn | The subscriber. |
eventId is your deduplication key. Delivery is at-least-once, so the same event can arrive
twice: store the id and ignore one you have already processed. See
Delivery and retries.
It is the same serviceId you send us on API calls. A value taken from an event can be sent
straight back to the API, and the number the operator team issued you with your grant is the number
that arrives here.
One destination can receive events for several services, since the destination is registered per short code while events come from each service on it. So this field is how you route an incoming event.
The events
eventType | When it fires |
|---|---|
subscription.created | A subscription opened, by any route: PIN, header enrichment, or the operator. |
subscription.renewed | A recurring charge succeeded and the period rolled forward. |
subscription.charge_failed | A renewal charge was attempted and failed. The subscription has not ended: it may recover on a later attempt. |
subscription.ended | The subscription is over, whatever the cause. |
subscription.language_changed | The subscriber changed the language they receive content in. |
treatAsNewSubscriber
subscription.created carries a treatAsNewSubscriber flag, and it exists because it was
impossible to answer on the legacy platform: is this person new to my service, or are they coming
back?
true: treat them as a first-time subscriber, with welcome content and introductory offers.false: they have subscribed to this service before and returned within the window where that still counts.
Use the flag rather than deriving it yourself. Your own records only show what you saw; the platform knows about subscriptions opened through routes you never observed.
Endings are not all the same
subscription.ended carries a reason, and they call for different responses:
- The subscriber chose to stop: respect it; do not market back to them on the strength of this event.
- Charges failed to the point of ending: a payment problem, not a rejection of your service.
- You ended it through the API: your own action, arriving back to you.
- Unspecified: the platform will not guess a cause it cannot establish.
A reason describes the channel the ending arrived through, not always the subscriber's intention. An ending you requested through the API says you asked: it does not say whether a subscriber pressed a button in your app to cause it. Only you know that.