Skip to main content
The webhook payload object is sent whenever an event triggers that you have subscribed to. Message webhooks re-use the same object. We have not added other events yet, but platform events will likely use a slightly different object structure due to their different nature. The Heyy API currently supports the following webhook event types:
  • message_inbound
  • message_outbound
  • message_status
  • message_echo
To listen to all outbound messages, including those not sent via Heyy (e.g. from the WhatsApp Business app, Instagram app, or Messenger app), subscribe to both message_outbound and message_echo events.

​
message_inbound webhook payload

The message_inbound event is fired when a new inbound message is received on one of your channels. 
{
  "id": "f8a2b1c3-4d5e-4f6a-9b0c-1d2e3f4a5b6c",
  "event": "message_inbound",
  "message": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "createdAt": "2026-03-13T23:29:35.583Z",
    "updatedAt": "2026-03-13T23:29:35.583Z",
    "chatId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
    "channelId": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f",
    "type": "message",
    "sender": "inbound",
    "sources": [
      {
        "type": "vendor"
      }
    ],
    "status": "delivered",
    "scheduledAt": null,
    "content": {
      "body": "Hello world",
      "attachments": []
    },
    "forwarded": false,
    "reactions": [],
    "errors": [],
    "history": [],
    "vendorId": "wamid.HBgNOTcyNTQ0Nzc4NzcwFQIAEhgUMzJCNzMyRzU0OTQ2MDdDNUE1RTIA",
    "timestamp": "2026-03-13T23:29:34.000Z",
    "vendorDetails": null,
    "isSensitive": false,
    "aiGenerationId": null,
    "metadata": {}
  }
}
Use this event to react to new customer messages, for example by:
  • Creating or updating conversations in your own system.
  • Triggering internal workflows.
  • Logging messages for analytics or compliance.

​
message_outbound webhook payload

The message_outbound event is fired when an outbound message is created and sent from Heyy (for example, by an agent, an automation, or an API call). Outbound messages sent not through Heyy (e.g. from the WhatsApp Business app, Instagram app, or Messenger app) are delivered via the message_echo event instead. 
{
  "id": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a",
  "event": "message_outbound",
  "message": {
    "id": "e5f6a7b8-c9d0-4e1f-2a3b-4c5d6e7f8a9b",
    "createdAt": "2026-03-13T23:15:24.646Z",
    "updatedAt": "2026-03-13T23:15:24.646Z",
    "chatId": "f6a7b8c9-d0e1-4f2a-3b4c-5d6e7f8a9b0c",
    "channelId": "a7b8c9d0-e1f2-4a3b-4c5d-6e7f8a9b0c1d",
    "type": "message",
    "sender": "outbound",
    "sources": [
      {
        "type": "inbox",
        "userId": "b8c9d0e1-f2a3-4b4c-5d6e-7f8a9b0c1d2e"
      }
    ],
    "status": "pending",
    "scheduledAt": null,
    "content": {
      "body": "Hello world"
    },
    "forwarded": false,
    "reactions": [],
    "errors": [],
    "history": [],
    "vendorId": "2847123456789012345",
    "timestamp": "2026-03-13T23:15:25.166Z",
    "vendorDetails": null,
    "isSensitive": false,
    "aiGenerationId": null,
    "metadata": {}
  }
}
You can use this event to:
  • Mirror outbound messages into your own data store.
  • Keep external CRMs or analytics systems in sync.
  • Track which system or agent generated which outbound messages.

​
message_status webhook payload

The message_status event is fired when the delivery status of a message changes (for example, from sent to delivered or read or failed, depending on the channel). 
{
  "id": "c9d0e1f2-a3b4-4c5d-6e7f-8a9b0c1d2e3f",
  "event": "message_status",
  "message": {
    "id": "d0e1f2a3-b4c5-4d6e-7f8a-9b0c1d2e3f4a",
    "createdAt": "2026-03-13T23:26:56.636Z",
    "updatedAt": "2026-03-13T23:26:59.512Z",
    "chatId": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
    "channelId": "f2a3b4c5-d6e7-4f8a-9b0c-1d2e3f4a5b6c",
    "type": "message",
    "sender": "outbound",
    "sources": [
      {
        "type": "inbox",
        "userId": "a3b4c5d6-e7f8-4a9b-0c1d-2e3f4a5b6c7d"
      }
    ],
    "status": "delivered",
    "scheduledAt": null,
    "content": {
      "body": "Hello world"
    },
    "forwarded": false,
    "reactions": [],
    "errors": [],
    "history": [
      {
        "event": "status_update",
        "newStatus": "pending",
        "timestamp": "2026-03-13T23:26:57.275Z"
      },
      {
        "event": "status_update",
        "newStatus": "sent",
        "timestamp": "2026-03-13T23:26:58.000Z"
      },
      {
        "event": "status_update",
        "newStatus": "delivered",
        "timestamp": "2026-03-13T23:26:58.000Z"
      }
    ],
    "vendorId": "a1f2e3d4-c5b6-4a97-8e8f-0d1c2b3a4e5f",
    "timestamp": "2026-03-13T23:26:57.275Z",
    "vendorDetails": null,
    "isSensitive": false,
    "aiGenerationId": null,
    "metadata": {}
  }
}
Typical uses for this event include:
  • Updating message delivery/read status in your own UI.
  • Powering reporting or analytics dashboards.
  • Triggering follow-up automations when a message reaches a specific status.

​
message_echo webhook payload

The message_echo event is fired when an outbound message was sent outside of Heyy in the same channel. For example, a reply sent from the WhatsApp Business app (coexistence), the Instagram app, the Messenger app. The payload uses the same structure as the other message webhooks: 
{
  "id": "b4c5d6e7-f8a9-4b0c-1d2e-3f4a5b6c7d8e",
  "event": "message_echo",
  "message": {
    "id": "d0e1f2a3-b4c5-4d6e-7f8a-9b0c1d2e3f4a",
    "createdAt": "2026-03-13T23:26:56.636Z",
    "updatedAt": "2026-03-13T23:26:59.512Z",
    "chatId": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
    "channelId": "f2a3b4c5-d6e7-4f8a-9b0c-1d2e3f4a5b6c",
    "type": "message",
    "sender": "unknown",
    "sources": [
      {
        "type": "inbox",
        "userId": "a3b4c5d6-e7f8-4a9b-0c1d-2e3f4a5b6c7d"
      }
    ],
    "status": "delivered",
    "scheduledAt": null,
    "content": {
      "body": "Hello world"
    },
    "forwarded": false,
    "reactions": [],
    "errors": [],
    "history": [
      {
        "event": "status_update",
        "newStatus": "delivered",
        "timestamp": "2026-03-13T23:26:58.000Z"
      }
    ],
    "vendorId": "wamid.HBgNOTcyNTQ0Nzc5NzcwFQIAERgSMzFDRURBNTA2RERyMUEwMUM0AA==",
    "timestamp": "2026-03-13T23:26:57.275Z",
    "vendorDetails": null,
    "isSensitive": false,
    "aiGenerationId": null,
    "metadata": {}
  }
}
You can use this event to:
  • Keep your records in sync when agents or users reply from the channel’s native app (e.g. WhatsApp Business, Instagram, Messenger) instead of the Heyy inbox.
  • Reconcile outbound messages across Heyy and other clients so conversations stay consistent.

​
Forward compatibility

As Heyy evolves, we may:
  • Add new webhook event types.
  • Add new fields to existing payloads.
To keep your integration robust:
  • Always ignore unknown fields.
  • Rely on the id and event fields for routing logic.
  • Treat the message object as an extensible resource that can gain additional properties over time.