Platform Events

Platform events (V3)

Gupshup delivers 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.

In the V3 payload, entry[].changes[].field identifies the event as platform-event, and entry[].changes[].value.type identifies its sub-type.

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

{
  "gs_app_id": "0a6f5e4d-1234-4c8b-9f21-7d3e5a9b1c40",
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "109876543210987",
      "time": 1760440000000,
      "changes": [
        {
          "field": "platform-event",
          "value": {
            "type": "connectivity-check",
            "initiator": "gupshup"
          }
        }
      ]
    }
  ]
}

Parameter definitions

Parameter	Data type	Description	Example
`gs_app_id`	String	ID of the Self Serve (SS) app associated with the callback.	`0a6f5e4d-1234-4c8b-9f21-7d3e5a9b1c40`
`object`	String	Object associated with the webhook notification.	`whatsapp_business_account`
`entry`	Array of objects	Contains the event entries.	See the example payload.
`entry[].id`	String	WhatsApp Business Account ID (WABA ID) associated with the event.	`109876543210987`
`entry[].time`	Number	Event timestamp expressed as Unix epoch time in milliseconds.	`1760440000000`
`entry[].changes`	Array of objects	Contains the event notifications for the entry.	See the example payload.
`entry[].changes[].field`	String	Identifies the event category. For platform notifications, this is `platform-event`.	`platform-event`
`entry[].changes[].value`	Object	Contains the platform event sub-type and its details.	See the example payload.
`entry[].changes[].value.type`	String	Platform event sub-type. Currently, `connectivity-check` is used to check callback endpoint reachability.	`connectivity-check`
`entry[].changes[].value.initiator`	String	Identifies the system that initiated the check.	`gupshup`

The app and WABA identifiers provide context for the callback. The connectivity check does not carry app-related business communication or message content.

Callback handling requirements

Recognize platform-event in entry[].changes[].field and connectivity-check in the corresponding value.type.
Return a 2xx HTTP status code to acknowledge connectivity checks.
Safely acknowledge and ignore unrecognized event categories 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.