Platform Events

Platform events

Gupshup sends platform-event notifications to your configured callback URL as part of its platform stability initiatives. These events are currently used exclusively for internal, system-level notifications. They cannot be subscribed to or configured from your end and do not contain business or message data.

Connectivity check

The connectivity-check sub-type verifies that your callback endpoint is healthy and reachable. Gupshup sends these checks periodically, and they may arrive at any time.

Your endpoint must return a 2xx HTTP status code to acknowledge the event and confirm that the callback URL is active. No business logic or message processing is required.

Example payload

{
  "app": "MyBusinessApp",
  "appId": "0a6f5e4d-1234-4c8b-9f21-7d3e5a9b1c40",
  "timestamp": 1760440000000,
  "version": 2,
  "type": "platform-event",
  "payload": {
    "type": "connectivity-check",
    "initiator": "gupshup"
  }
}

Parameter definitions

Parameter	Data type	Description	Example
`app`	String	Name of the Self Serve (SS) app associated with the callback.	`MyBusinessApp`
`appId`	String	ID of the Self Serve (SS) app associated with the callback.	`0a6f5e4d-1234-4c8b-9f21-7d3e5a9b1c40`
`timestamp`	Number	Event timestamp expressed as Unix epoch time in milliseconds.	`1760440000000`
`version`	Number	Event payload format version.	`2`
`type`	String	Top-level event type. For platform notifications, this is `platform-event`.	`platform-event`
`payload`	Object	Contains the platform event sub-type and its details.	See the example payload.
`payload.type`	String	Platform event sub-type. Currently, `connectivity-check` is used to check callback endpoint reachability.	`connectivity-check`
`payload.initiator`	String	Identifies the system that initiated the check.	`gupshup`

The app and appId fields identify the app associated with the callback; the event does not carry app-related business communication or message content.

Callback handling requirements

Recognize the top-level platform-event type and the connectivity-check sub-type.
Return a 2xx HTTP status code to acknowledge connectivity checks.
Safely acknowledge and ignore unrecognized event types or sub-types without causing errors, exceptions, or processing failures.
Do not trigger business logic or message processing for connectivity checks.

Additional sub-types may be introduced under platform-event in the future. Build your callback handler to tolerate new sub-types gracefully.