Events generated by AWS End User Messaging Social

When you turn on event publishing for a WhatsApp Business Account (WABA), AWS End User Messaging Social sends events to the event destination that you configure for the WABA, which is either an Amazon SNS topic or an Connect Customer instance. For more information about configuring an event destination, see Message and event destinations in AWS End User Messaging Social. The events that are delivered to your event destination come from two different sources:

• Relayed from WhatsApp – Most events originate as webhook notifications from Meta's WhatsApp Business Platform. AWS End User Messaging Social receives the webhook, maps it to a AWS End User Messaging Social event, and relays it to your event destination. The message status events (such as delivered, read, sent, and failed) and inbound customer messages are relayed from WhatsApp.

• Generated by AWS End User Messaging Social – A smaller set of events are generated by AWS End User Messaging Social itself, not relayed from Meta. AWS End User Messaging Social generates these events to tell you the outcome of an asynchronous request that you made, such as sending a message or a call event. These events are described in this topic.

Generated events are delivered to your configured event destination in the same format as the events that are relayed from WhatsApp.

Generated event types

AWS End User Messaging Social generates the following events. The handover events tell you whether AWS End User Messaging Social successfully handed your request off to WhatsApp, or whether the hand-off failed.

Event	Description
WhatsApp Message Handover Succeeded	AWS End User Messaging Social successfully handed off a message that you sent with SendWhatsAppMessage to WhatsApp for delivery. A successful hand-off does not guarantee that your message is delivered to the recipient. The message status events that are relayed from WhatsApp report the delivery status separately.
WhatsApp Message Handover Failed	AWS End User Messaging Social could not hand off a message that you sent with SendWhatsAppMessage to WhatsApp. This happens, for example, when the WABA is not enabled for sending. It can also happen when AWS End User Messaging Social cannot hand off the message within the retry period. In that case, AWS End User Messaging Social drops the message.
WhatsApp Call Handover Succeeded	AWS End User Messaging Social successfully handed off a call event that you sent with SendWhatsAppCallEvent to WhatsApp.
WhatsApp Call Handover Failed	AWS End User Messaging Social could not hand off a call event that you sent with SendWhatsAppCallEvent to WhatsApp. The event includes an error that explains why the hand-off failed, such as an invalid destination, a missing call permission, or calling not being enabled for the business.
WhatsApp Unknown Notification Received	AWS End User Messaging Social received a notification that it could not map to a known event type, or encountered an error while delivering an event to your event destination. The raw notification is included so that you can inspect it.

You distinguish these events in the payload that is delivered to your Amazon SNS topic or Connect Customer instance. The handover events for a call use the calls field in the embedded webhook entry, and the handover events for a message use the statuses field.

Delivery to the default EventBridge event bus

In addition to your configured Amazon SNS or Connect Customer event destination, you also receive the handover events, the message status events, and the WhatsApp Unknown Notification Received event on the default Amazon EventBridge event bus in your AWS account. On the default event bus, you identify each event by its detail-type value. You can write rules that match on this value. For the list of detail-type values and example events, see Monitoring with Amazon EventBridge.

Personally identifiable information is omitted

The event copy that you receive on the default event bus omits personally identifiable information, including the biz_opaque_callback_data value. To receive the full event, including biz_opaque_callback_data, use your Amazon SNS or Connect Customer event destination.

Correlating a generated event with your request

To correlate a handover event with the request that produced it, include a biz_opaque_callback_data value in the message or call event that you send. With this field set, you receive the same value back on the corresponding handover event, on both the success event and the failure event. This lets you match a handover event to the specific SendWhatsAppMessage or SendWhatsAppCallEvent request that you made.

You pass biz_opaque_callback_data through to WhatsApp, using the same field name that WhatsApp uses. AWS End User Messaging Social only echoes the value that you provide; it does not generate one for you. If you do not include it in your request, you still receive the handover event, but without the biz_opaque_callback_data field.

The biz_opaque_callback_data value is included only on the event that is delivered to your Amazon SNS or Connect Customer event destination. It is not included on the copy that is sent to the default EventBridge event bus.

Example: failed call handover event (Amazon SNS)

The following example shows the message that is published to an Amazon SNS event destination for a failed call handover. The embedded whatsAppWebhookEntry uses the calls field, includes the biz_opaque_callback_data value that you provided, and includes an errors array that describes why the hand-off failed.

{
    "aws_account_id": "111122223333",
    "message_timestamp": "2025-10-03T04:49:25Z",
    "messageId": "f0e1d2c3-b4a5-6978-8a9b-0c1d2e3f4a5b",
    "context": {
        "meta_waba_ids": [
            {
                "arn": "arn:aws:social-messaging:ca-central-1:111122223333:waba/waba-11111111111111111111111111111111",
                "waba_id": "1163793972139053"
            }
        ],
        "meta_phone_number_ids": [
            {
                "arn": "arn:aws:social-messaging:ca-central-1:111122223333:phone-number-id/phone-number-id-22222222222222222222222222222222",
                "meta_phone_number_id": "574086085794038"
            }
        ]
    },
    "whatsAppWebhookEntry": {
        "id": "1163793972139053",
        "changes": [
            {
                "field": "calls",
                "value": {
                    "messaging_product": "whatsapp",
                    "metadata": {
                        "display_phone_number": "15815555555",
                        "phone_number_id": "574086085794038"
                    },
                    "calls": [
                        {
                            "id": "wacid.ABGGFlA5Fpa",
                            "to": "15559998888",
                            "from": "15815555555",
                            "status": "WhatsApp Call Handover Failed",
                            "biz_opaque_callback_data": "my-call-correlation-id-456",
                            "timestamp": "1759466965",
                            "errors": [
                                {
                                    "code": 138002,
                                    "title": "Concurrent calls limit reached",
                                    "message": "Concurrent calls limit reached"
                                }
                            ]
                        }
                    ]
                }
            }
        ]
    }
}

Additional resources

For the list of events and detail-type values that AWS End User Messaging Social sends to Amazon EventBridge, and more event examples, see Monitoring with Amazon EventBridge. For the message status values that are relayed from WhatsApp, see WhatsApp message status.