Notifications

Notifications are webhooks from Setu that provide the data you requested.

The base_url is your server URL configured to receive notifications, which is the Notification endpoint you shared during template creation step.

Insights generated notification

This notification is used to communicate the generated insights which was requested by you in Create Insight Report API.

Field Descriptions

The table below describes each field in the notification payload:

Field	Type	Description
`version`	`string`	Version of the Insights API (e.g., "v3")
`notificationId`	`UUID`	Unique identifier for this specific notification
`type`	`string`	Type of notification (always "INSIGHT_STATUS_UPDATE" for insights)
`timestamp`	`datetime`	ISO 8601 timestamp when the notification was sent
`reportId`	`UUID`	Reference ID of the insights generation report. Use this to fetch insights via the Get Insights API
`status`	`enum`	Status of insight processing: `SUCCESS`, `PARTIAL_SUCCESS`, or `FAILURE`
`message`	`string`	Human-readable message describing the current status
`additionalInfo`	`object`	Passthrough field for additional metadata

Success Case

When all insights are successfully generated, you'll receive a notification with status: "SUCCESS". The actual insights data will be available via the Get Insights API.

{
  "version": "v3",
  "notificationId": "b7c8d9e0-f1a2-4b3c-8d4e-9f5a6b7c8d9e",
  "type": "INSIGHT_STATUS_UPDATE",
  "timestamp": "2025-06-18T09:39:27.244Z",
  "reportId": "8af477ff-d97e-4eda-a6c0-b5acd5714262",
  "status": "SUCCESS",
  "message": "Insights generation completed successfully",
  "additionalInfo": {}
}

Partial Success Case

When some insights are generated successfully while others fail, you'll receive a notification with status: "PARTIAL_SUCCESS". Check the Get Insights API for insight data and any errors.

{
  "version": "v3",
  "notificationId": "c8d9e0f1-a2b3-4c5d-9e6f-7a8b9c0d1e2f",
  "type": "INSIGHT_STATUS_UPDATE",
  "timestamp": "2025-06-18T09:39:27.244Z",
  "reportId": "8af477ff-d97e-4eda-a6c0-b5acd5714262",
  "status": "PARTIAL_SUCCESS",
  "message": "Generation of some insights failed. Call get insights to get the details",
  "additionalInfo": {}
}

Failure Case

When the entire insight generation process fails, you'll receive a notification with status: "FAILURE".

{
  "version": "v3",
  "notificationId": "d9e0f1a2-b3c4-4d5e-9f6a-8b9c0d1e2f3a",
  "type": "INSIGHT_STATUS_UPDATE",
  "timestamp": "2025-06-18T09:39:27.244Z",
  "reportId": "8af477ff-d97e-4eda-a6c0-b5acd5714262",
  "status": "FAILURE",
  "message": "Insights generation failed",
  "additionalInfo": {}
}