Events
Notifications of things that happen on the network, or to Endpoints
A powerful feature of the Stacuity network is being able to notified about events which happen, so you can trigger application-specific functionality. Event notifications are sent in real time (normally within a second of the event occurring), but if they can't be sent immediately then we store for a limited period them until they can. So, in the case of disruption or maintenance, data won't be lost - as long as the disruption doesn't last too long.
We try to maintain the order of events for each endpoint which are going to a particular destination. So, if an endpoint does two things - one after an other - we won't send the second event until we have successfully sent the first. However, delivery ordering of events generated by different endpoints isn't guaranteed - to ensure that we can send events quickly enough to keep-up.
We also store all events within our platform, allowing you to query and search for events even if you hadn't configured them to be sent to you at the time. These events are retained for a period, and then deleted.
There are three concepts involved in events:
- Event Types
- Event Handlers
- Event Maps
Events are triggered by the behaviour of Endpoints as they use the cellular network - such as starting new data sessions, or sending an SMS
Events are all recorded in the stacuity platform and can be viewed from the portal.
Event Format
Each event contains a JSON payload with the following attributes:
eventId = A Uniqiue identifier for this individual event
eventTime The timestamp of when the event occured in UTC
eventType A string identifying the specific type of event (see Event Types for a list)
endpointId The ID of the endpoint that triggered the event. This attribute is available if the event scope is 'Endpoint'
routingTargetId The ID of the Routing Target that triggered the event. This attribute is available if event scope is 'Routing Target'
detail A Key/Value object containing specific details relating to the event.
Event Types
Consult the Events API reference for the full details of each type of event.
openapi: 3.1.0
info:
title: Stacuity Events
version: 1.0.0
webhooks:
EndpointKeyValueUpdated_v1:
post:
requestBody:
description: Triggered when an Key/Value for the Endpoint Is updated
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/eventmeta"
- $ref: "#/components/schemas/EndpointKeyValueUpdated_v1"
responses:
"200":
description: A 200 to indicate the event was successfully received
EndpointOriginatedSMS_v1:
post:
requestBody:
description: Triggered when endpoint sends an SMS
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/eventmeta"
- $ref: "#/components/schemas/EndpointOriginatedSMS_v1"
responses:
"200":
description: A 200 to indicate the event was successfully received
EndpointOriginatedUSSD_v1:
post:
requestBody:
description: Triggered when endpoint sends an USSD message
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/eventmeta"
- $ref: "#/components/schemas/EndpointOriginatedUSSD_v1"
responses:
"200":
description: A 200 to indicate the event was successfully received
EndpointDataSessionCreated_v1:
post:
requestBody:
description: Triggered when endpoint successfully starts a data session
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/eventmeta"
- $ref: "#/components/schemas/EndpointDataSessionCreated_v1"
responses:
"200":
description: A 200 to indicate the event was successfully received
EndpointDataSessionCreateFailed_v1:
post:
requestBody:
description: Triggered when endpoint fails to establish a data session
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/eventmeta"
- $ref: "#/components/schemas/EndpointDataSessionCreateFailed_v1"
responses:
"200":
description: A 200 to indicate the event was successfully received
EndpointDataSessionDeleted_v1:
post:
requestBody:
description: Triggered when a data session is terminated
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/eventmeta"
- $ref: "#/components/schemas/EndpointDataSessionDeleted_v1"
responses:
"200":
description: A 200 to indicate the event was successfully received
EndpointDataSessionExtended_v1:
post:
requestBody:
description: Triggered when an established data session periodically renewed
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/eventmeta"
responses:
"200":
description: A 200 to indicate the event was successfully received
EndpointDataSessionModified_v1:
post:
requestBody:
description: Triggered when an established data session changes properties
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/eventmeta"
responses:
"200":
description: A 200 to indicate the event was successfully received
EndpointAuthenticated_v1:
post:
requestBody:
description: Triggered when an endpoint attaches to a carrier network
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/eventmeta"
- $ref: "#/components/schemas/EndpointAuthenticated_v1"
responses:
"200":
description: A 200 to indicate the event was successfully received
EndpointLocationUpdated_v1:
post:
requestBody:
description: Triggered when an endpoint attempts to establish a data session
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/eventmeta"
- $ref: "#/components/schemas/EndpointLocationUpdated_v1"
responses:
"200":
description: A 200 to indicate the event was successfully received
EndpointPurged_v1:
post:
requestBody:
description: Triggered when an endpoint is removed from the network
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/eventmeta"
- $ref: "#/components/schemas/EndpointPurged_v1"
responses:
"200":
description: A 200 to indicate the event was successfully received
EndpointCountryChanged_v1:
post:
requestBody:
description: Triggered when an endpoint attaches to a carrier network in a different country to its last attach.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/eventmeta"
- $ref: "#/components/schemas/EndpointCountryChanged_v1"
responses:
"200":
description: A 200 to indicate the event was successfully received
EndpointServingOperatorChanged_v1:
post:
requestBody:
description: Triggered when an endpoint attaches to a different carrier network.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/eventmeta"
- $ref: "#/components/schemas/EndpointServingOperatorChanged_v1"
responses:
"200":
description: A 200 to indicate the event was successfully received
EndpointImeiChanged_v1:
post:
requestBody:
description: Triggered when an endpoint attaches with a different IMEI
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/eventmeta"
- $ref: "#/components/schemas/EndpointImeiChanged_v1"
responses:
"200":
description: A 200 to indicate the event was successfully received
components:
schemas:
eventmeta:
required:
- eventId
- eventType
- eventTime
properties:
eventId:
type: string
format: uuid
description: Unique Identifier for the event
eventType:
type: string
description: Name of the Event Type
eventTime:
type: string
format: date-time
description: Timestamp the event was triggered
endpointId:
type: string
format: uuid
description: ID of the endpoint that triggered the event.
EndpointLocationUpdated_v1:
required:
- detail:
properties:
detail:
type: object
properties:
mcc:
type: string
description: The Mobile Country Code of the Carrier Network
mnc:
type: string
description: The Mobile Network Code of the Carrier Network
imei:
type: string
description: The IMEI of the device the endpoint is using
ratType:
type: string
description: The Radio access type
signallingSource:
type: string
description: The Signalling System used for the location update
required:
- mcc
- mnc
- imei
- ratType
- signallingSource
EndpointDataSessionCreateFailed_v1:
required:
- detail:
properties:
detail:
type: object
properties:
mcc:
type: string
description: The Mobile Country Code of the Carrier Network
mnc:
type: string
description: The Mobile Network Code of the Carrier Network
imei:
type: string
description: The IMEI of the device the endpoint is using
LocationAreaCode:
type: string
description: The Location Area of the Serving Cell
ServiceAreaCode:
type: int
description: The Location Area of the Serving Cell
TrackingAreaCode:
type: int
description: The Location Area of the Serving Cell
CellIdentifier:
type: int
description: The ID of the Serving Cell
Message:
type: string
description: Reason for failure
required:
- mcc
- mnc
- imei
- ratType
- Message
EndpointDataSessionDeleted_v1:
required:
- detail:
properties:
detail:
type: object
properties:
UplinkBytes:
type: int
description: The number of bytes sent from the endpoint during the session
DownlinkBytes:
type: int
description: The number of bytes sent to the endpoint during the session
DurationSeconds:
type: int
description: The duration of the session in seconds
required:
- UplinkBytes
- DownlinkBytes
- DurationSeconds
EndpointKeyValueUpdated_v1:
required:
- detail:
properties:
detail:
type: object
properties:
UpdateType:
type: string
description: The type of update
Source:
type: string
description: Where the update was made from
UpdateKey:
type: string
description: The key that was updated
UpdateValue:
type: string
description: The updated value
required:
- UpdateType
- Source
EndpointOriginatedUSSD_v1:
required:
- detail:
properties:
detail:
type: object
properties:
Message:
type: string
description: The text of the message
RawHex:
type: string
description: The Hex encoded message
required:
- Message
- RawHex
EndpointOriginatedSMS_v1:
required:
- detail:
properties:
detail:
type: object
properties:
Destination:
type: string
description: The destination number the SMS was sent to
Message:
type: string
description: The text of the message
RawHex:
type: string
description: The Hex encoded message
ReplyPath:
type: bool
description: If Reply via same SMSC was set
UserDataHeaderIndicator:
type: bool
description: If UDHI is set
StatusReportRequest:
type: bool
description: If status reports are requested
ValidityPeriodFormat:
type: string
description: Message validitiy time
RejectDuplicates:
type: bool
description: Reject messages with the same Message Reference
MessageReference:
type: string
description: The message reference ID
ProtocolIdentifier:
type: string
description: The Protocol ID or PID
DataCodingScheme:
type: string
description: Data Coding Scheme of the message
UserDataLength:
type: string
description: Length of the user data
UserDataHex:
type: string
description: The Hex encoded user data
required:
- Destination
- Message
- RawHex
EndpointDataSessionCreated_v1:
required:
- detail:
properties:
detail:
type: object
properties:
mcc:
type: string
description: The Mobile Country Code of the Carrier Network
mnc:
type: string
description: The Mobile Network Code of the Carrier Network
imei:
type: string
description: The IMEI of the device the endpoint is using
LocationAreaCode:
type: string
description: The Location Area of the Serving Cell
ServiceAreaCode:
type: int
description: The Location Area of the Serving Cell
TrackingAreaCode:
type: int
description: The Location Area of the Serving Cell
CellIdentifier:
type: int
description: The ID of the Serving Cell
ratType:
type: string
description: The Radio access type
signallingSource:
type: string
description: The Signalling System used for the location update
required:
- mcc
- mnc
- imei
- ratType
- signallingSource
EndpointAuthenticated_v1:
required:
- detail:
properties:
detail:
type: object
properties:
signallingSource:
type: string
description: The Signalling System used for the location update
required:
- signallingSource
EndpointPurged_v1:
required:
- detail:
properties:
detail:
type: object
properties:
signallingSource:
type: string
description: The Signalling System used for the location update
required:
- signallingSource
EndpointSteered_v1:
required:
- detail:
properties:
detail:
type: object
properties:
mcc:
type: string
description: The Mobile Country Code of the Carrier Network
mnc:
type: string
ratType:
type: string
description: The Radio access type
signallingSource:
type: string
description: The Signalling System used for the location update
required:
- signallingSource
- mcc
- mnc
- ratType
EndpointCountryChanged_v1:
required:
- detail:
properties:
detail:
type: object
properties:
NewIso3:
type: string
description: The 3 character ISO 3166 Country Code the Endpoint is now attached in
NewIso2:
type: string
description: The 2 character ISO 3166 Country Code the Endpoint is now attached in
Country:
type: string
description: The name of the country the Endpoint is now attached in
required:
- NewIso3
- NewIso2
- Country
EndpointImeiChanged_v1:
required:
- detail:
properties:
detail:
type: object
properties:
NewImei:
type: string
description: The IMEI number of the device now using the endpoint
required:
- NewImei
EndpointServingOperatorChanged_v1:
required:
- detail:
properties:
detail:
type: object
properties:
NewMcc:
type: string
description: The Mobile Country Code of the Carrier Network the endpoint is now using
NewMnc:
type: string
description: The Mobile Network Code of the Carrier Network the endpoint is now using
Operator:
type: string
description: The name of the Carrier Network the endpoint is now using
Updated 12 months ago