> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifense.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

| Type | Description        |
| ---- | ------------------ |
| `1`  | Escalation started |
| `2`  | Escalation ended   |
| `3`  | Low credit balance |

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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "accountId": "00000000-0000-0000-0000-000000000000", // UUID
  "creditsRemaining": 0 // number
}
```