Incoming Events


You can receive your incoming events for channels supported by the Business Messaging API in your own systems, by registering a webhook in the Channels-app. After registering an HTTPS web address you will start receiving the incoming events.

Note These events do not include the receiving of messages; please refer to the following docs for that: Incoming messages.

Note In the case of offboarding, the registered webhook(s) are removed and any incoming events will therefore not be forwarded to the webhook(s) any longer.

Receiving events

In order to receive the incoming events, you need to build a web service where our systems can deliver the events. This is called a webhook. Via the webhook, you will be notified by of the new event content and metadata using a POST call to your registered web service in the JSON content format. To indicate you have received the events you need to reply with an HTTP 200 OK status code. You do not need to send any content back in the reply. You can receive incoming events from Instagram using these webhooks.

If your web service returns anything else other than response code 200 OK, we will consider the event as not having been delivered. Our services will retry delivery (for a maximum of three times). In case of a timeout, we will consider the event delivered.

Contents format

Webhook calls are made using HTTP POST with the Content-Type application/json and are in the UTF-8 character set. You will receive a JSON object like this on the registered URLs:

fromInformation about the sender. (See below)
toInformation about the recipient of the event. (See below)
eventThe event that occurred. (See below)
timeUtcThe time (yyyy-MM-ddTHH:mm:ss) of the event in UTC.
channelThe event channel. (e.g. "Instagram")


numberIdentifier of the source from where the event originated.


numberIdentifier to which the event was sent.


ValueTypeDescriptionInstagram MessagingGoogle Business MessagingMobilePushFacebook Messenger
referenceA reference to the object or message that triggered the event.
typeMessageDeleteOccurs when a message is deleted by the end-user.xx
StoryMentionOccurs when a story mention is
UserAgentRequestedOccurs when a user agent is requested by the
ClientInstalledOccurs when a new client is installed by an
ClientUpdatedOccurs when an existing client has been updated by the
MessageDismissedOccurs when a message is dismissed/swiped away by the
MessageOpenedOccurs when a message is opened by the
OptInSubscribedWhen an user has subscribed on your opt-in messages.xx
OptInExtendedWhen an user has extended their subscription on your opt-in messages by pressing the Continue messages button just before the token expires.xx
OptInStoppedWhen a subscription on opt-in messages has been expired or an user has not extended their subscription on your opt-in messages.xx
OptInSuspendedWhen an user suspends their opt-in messages subscription by pressing the Stop these messages button. Resulting in a temporarily block.xx
OptInResumedWhen an user resumes their opt-in messages subscription after a suspension by pressing the Resume these messages button.xx
customCan contain information in context of the event.
StoryMentionStory url
ClientInstalled/UpdatedProfile data



Not all channels support the same events. For details and documentation on an event type, we ask you to refer to documentation of the specific channel.

Example event

    "from": {
        "number": "6f2de4d4cc6aa17da2e11c3bff5843aa"
    "to": {
        "number": "5d68d44a356b72b899221e45c676cc23"
    "event": {
        "type": "MessageDelete",
        "reference": "453563216"
    "timeUtc": "2021-07-05T17:08:45",
    "channel": "Instagram"


If you want your systems to be certain that requests are sent from's systems and are not initiated by a spoofing third party, you can limit the reception of events to those originating from our IP ranges.

The IP ranges of the services that send events and could be used for our outbound traffic are:


Note You should whitelist all these IP ranges. We cannot guarantee an exact IP address of specific services within these ranges as the servers can change IP within this range at any time.