Callbacks

Notifense requires you to specify a callback URL when creating your account. This callback URL will be called when an event is escalated by the end user. The following callback types can be sent to your callback URL:

Callbacks can contain an isTest property. If this property is true, this callback is meant for validation of the implementation of the callback on your end.

The body of the callback is a JSON document with the following structure:

{
  "type": 0, // number: The type of callback
  "data": {
    // object: Depends on the callback type (see below)
  },
  "isTest": false // boolean: Whether this callback is a test for implementation validation
}

1 - Escalation started

An end user has requested to escalate an event.

This callback contains an asset ID and a timestamp. Your application MUST start sending all incoming (real-time) telemetry data for this asset to the Notifense API. In addition, your application MUST send all historical telemetry data available for that asset, starting from at least the provided timestamp up to the current time. You may also send older telemetry data you have available, especially if it could be significant for asset recovery purposes.

If you are using the event generation service, you can also send the telemetry data there. In this case, set the isPersisted flag to true for messages sent for this asset.

The data property of this callback has the following structure:

{
  "accountId": "00000000-0000-0000-0000-000000000000", // UUID
  "assetId": "00000000-0000-0000-0000-000000000000", // UUID
  "eventId": "00000000-0000-0000-0000-000000000000", // UUID
  "externalId": "", // string: Asset ID in your application
  "telemetryRequestedFrom": "2025-01-01T01:02:03+00:00" // ISO 8601 timestamp
}

2 - Escalation ended

The event has been deescalated or recovery has concluded.

This callback contains an asset ID. Your application should stop sending all incoming (real-time) telemetry data for this asset to the Notifense API.

If you are using the event generation service, set the isPersisted flag to false for messages sent for this asset.

The data property of this callback has the following structure:

{
  "accountId": "00000000-0000-0000-0000-000000000000", // UUID
  "assetId": "00000000-0000-0000-0000-000000000000", // UUID
  "eventId": "00000000-0000-0000-0000-000000000000", // UUID
  "externalId": "" // string: Asset ID in your application
}

3 - Low credit balance

The credit balance on your account has reached the low credits threshold configured in your account.

This callback is only sent if your account is on the manual payment plan.

The data property of this callback has the following structure:

{
  "accountId": "00000000-0000-0000-0000-000000000000", // UUID
  "creditsRemaining": 0 // number
}