Platform Webhook Event: Connectivity Check

Gupshup is introducing a new callback event type, platform-event, which is delivered to the callback URL configured for your app. This event is used only for internal, system-level notifications. You cannot subscribe to it or configure it, and it does not carry any app or message data.

The first sub-type under this event is connectivity-check. Gupshup sends it to your callback URL to verify that your endpoint is healthy and reachable.

Action required: Make sure your callback handler returns a 2xx HTTP response for this event and does not fail on event types it does not recognise.

How it works

1. Gupshup sends a platform-event callback with sub-type connectivity-check to your configured callback URL. This can happen at any time.
2. Your endpoint responds with a 2xx HTTP status code.
3. Gupshup treats a 2xx response as confirmation that your callback URL is active.

No business logic or message processing is required for this event.

Payload

The payload format depends on the callback version configured for your app.

V3 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"
          }
        }
      ]
    }
  ]
}

V2 payload

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

What you need to do

• Return a 2xx response. Ensure your callback handler recognises the platform-event type and the connectivity-check sub-type, and responds with a 2xx status code.
• Ignore unknown events safely. Make sure unknown or new event types do not cause errors, exceptions, or processing failures in your system. Acknowledge them and ignore them.
• Skip business logic. This event carries no app or message data, so no processing is required beyond the acknowledgement.

Example handler

The example below is illustrative. Adapt it to your own stack.

app.post("/gupshup/callback", (req, res) => {
  const body = req.body;

  // V2: type === "platform-event"
  // V3: entry[].changes[].field === "platform-event"
  const isV2PlatformEvent = body.type === "platform-event";
  const isV3PlatformEvent = body.entry?.some((e) =>
    e.changes?.some((c) => c.field === "platform-event")
  );

  if (isV2PlatformEvent || isV3PlatformEvent) {
    // Connectivity check (or a future platform-event sub-type).
    // Acknowledge and do nothing else.
    return res.sendStatus(200);
  }

  // ...handle your existing message / status events here...
  return res.sendStatus(200);
});

Future sub-types

Additional sub-types may be introduced under platform-event in the future. Build your handler to tolerate new sub-types gracefully: acknowledge with a 2xx and ignore any you do not need.

FAQ

Can I subscribe to or unsubscribe from platform-event?
No. It is used for internal, system-level notifications and is not configurable from your end.

Does this event contain message or app data?
No. It carries no app or message-related data.

What happens if my endpoint does not return a 2xx?
Gupshup uses the 2xx response to confirm that your callback URL is active. A non-2xx response indicates the endpoint may not be healthy or reachable, so make sure your handler acknowledges this event.