Sendzen API Documentation
HomeGetting StartedChangelog
HomeGetting StartedChangelog
Visit Website
Sign In
Create an account
  1. Messages
  • Start Guide
    • Getting Started
    • API Reference
  • Messages
    • Template Messages
      • Send Text Message
      • Send Interactive Message
      • Send Media Message
    • Session Messages
      • Send Text Message
      • Send Image Message
      • Send Video Message
      • Send Audio Message
      • Send Document Message
      • Send Interactive Reply Message
    • Incoming Messages
      • Received Text Message
      • Received Message with Reaction
      • Received Media Message with Image
      • Received Callback from a Quick Reply Button Click
    • Other
      • Message Status & Typing Indicator
  • Template
    • List Templates
      GET
    • Create Template
      POST
    • Delete Template
      DELETE
    • Upload Media
      POST
  • Partner
    • Integration Guide
  • Project
    • Create Project
      POST
    • List Projects
      GET
    • Update Project
      PUT
    • Retrieve Project
      GET
  • WABA
    • List WABA
      GET
    • Retrieve WABA Details from Meta
      GET
    • Retrieve WhatsApp Business Profile Detail
      GET
    • Update WhatsApp Business Profile
      POST
    • Upload WhatsApp Business Profile
      POST
  • Activity Logs
    • All Event Logs
      GET
    • Incoming Message Logs
      GET
    • Message Status Logs
      GET
    • Other Event Logs
      GET
    • Multiple Event Types
      GET
  • Knowledge Base
    • Programming Languages
      • Python
      • Node.js
      • PHP
      • Laravel
      • Java
      • C# .NET
    • Onboarding
      • WhatsApp Setup
    • Product
      • Changelog
  • Schemas
    • Schemas
      • Template Message
      • 401/403 Message Response
      • AccountLoginRequest
      • APIKeyDto
      • ReadTypingIndicatorRequest
      • AccountRegisterRequest
      • TypingIndicator
      • PartnerConfigDto
      • LoginResponse
      • PartnerInfoDto
      • WABASignUp
      • OrderCheckoutDto
      • OrderDto
      • OrderStatusEnum
      • PaymentGatewayDto
    • Knowledge Base
    • Address
    • Account
    • CommonResponse
    • AccountDetailDto
    • CreateOrUpdateProjectRequest
    • Contact
    • Error
    • ContactName
    • Button
    • ErrorResponse
    • CarouselCard
    • Email
    • ClientData
    • Component
    • ProjectDetailDto
    • ProjectWABADetail
    • Interactive
    • WABADetail
    • InteractiveAction
    • WABADto
    • InteractiveBody
    • CreateTemplateRequest
    • InteractiveButton
    • InteractiveFooter
    • CreateWebhookConfigRequest
    • InteractiveHeader
    • InteractiveMedia
    • Example
    • InteractiveProductItem
    • InteractiveProductSection
    • InteractiveReply
    • InteractiveRow
    • InteractiveSection
    • Location
    • Media
    • MessageRequest
    • MessageResponse
    • MessageTemplate
    • Organization
    • LimitedTimeOffer
    • Phone
    • Reaction
    • Response
    • TemplateAction
    • NamedParameter
    • TemplateButtons
    • TemplateCarousel
    • TemplateComponent
    • TemplateCurrency
    • PaginatedWebhookLogsResponse
    • TemplateDateTime
    • PartnerClientSession
    • TemplateLimitedTimeOffer
    • PartnerClientSessionDto
    • TemplateMedia
    • TemplateParameter
    • TemplateProductItem
    • TemplateSection
    • TemplateTapTargetConfiguration
    • SupportedApp
    • Text
    • Url
    • WhatsAppBusinessProfile
    • UploadMedia
    • Webhook
    • WebhookConfigDto
    • WebhookLogDto
  1. Messages

Incoming Messages

Incoming messages received from a number are forwarded to you via a WhatsApp webhook.
WhatsApp sends a notification to SendZen, and SendZen forwards that notification to the API endpoint you’ve configured.
A WhatsApp webhook is a way for the WhatsApp Business Platform to send real-time data to an application when specific events occur, such as receiving a new message or a message status change.
Instead of an application constantly "polling" WhatsApp for updates, the platform automatically sends an HTTP notification to a URL, making the process more efficient. This allows for real-time automation, such as instantly storing incoming messages in a database or triggering automated replies.

How SendZen webhooks work#

1.
You create a webhook endpoint on your server (for example: https://api.yourapp.com/sendzen/webhook).
2.
You register this URL inside app.sendzen.io in left hand side-bar → Webhooks.
3.
You choose which events you want to receive (for example: incoming_message, delivery_status).
4.
Whenever the event happens, SendZen sends an HTTP POST request with a JSON payload to your URL.
5.
Your server returns a 2xx status code to confirm that the event was processed.

Setting up a webhook in SendZen#

1.
Log in to app.sendzen.io and select your account.
2.
Go to Webhooks.
3.
Click Add webhook.
4.
Fill in:
Webhook URL: Your HTTPS endpoint.
Secret: Optional. We will use this to sign webhook requests.
Events: Select one or more events you want to subscribe to.
5.
Click Save.

Request format#

All webhooks are HTTP POST requests with a JSON body.
Method: POST
URL: Your configured webhook URL
Content type: application/json

Received Text Message with Show Security Notifications#

{
    "object": "whatsapp_business_account",
    "entry": [
        {
            "id": "8856996819413533",
            "changes": [
                {
                    "value": {
                        "messaging_product": "whatsapp",
                        "metadata": {
                            "display_phone_number": "<PHONE_NUMBER>",
                            "phone_number_id": "27681414235104944"
                        },
                        "contacts": [
                            {
                                "profile": {
                                    "name": "<CONTACT_NAME>"
                                },
                                "wa_id": "<WA_ID>"
                            }
                        ],
                        "messages": [
                            {
                                "from": "<FROM_PHONE_NUMBER>",
                                "id": "ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
                                "identity": {
                                    "acknowledged": true,
                                    "created_timestamp": 1602532300000,
                                    "hash": "Sjvjlx8G6Z0="
                                },
                                "text": {
                                    "body": "Hi from new number 3601"
                                },
                                "timestamp": "1602532300",
                                "type": "text"
                            }
                        ]
                    },
                    "field": "messages"
                }
            ]
        }
    ]
}

Received Message with Reaction#

{
    "object": "whatsapp_business_account",
    "entry": [
        {
            "id": "8856996819413533",
            "changes": [
                {
                    "value": {
                        "messaging_product": "whatsapp",
                        "metadata": {
                            "display_phone_number": "<PHONE_NUMBER>",
                            "phone_number_id": "27681414235104944"
                        },
                        "contacts": [
                            {
                                "profile": {
                                    "name": "<CONTACT_NAME>"
                                },
                                "wa_id": "<WA_ID>"
                            }
                        ],
                        "messages": [
                            {
                                "from": "sender_wa_id",
                                "id": "message_id",
                                "timestamp": "message_timestamp",
                                "type": "reaction",
                                "reaction": {
                                    "emoji": "<emoji>",
                                    "messsage_id": "<WAMID>"
                                }
                            }
                        ]
                    },
                    "field": "messages"
                }
            ]
        }
    ]
}

Received Media Message with Image#

{
    "object": "whatsapp_business_account",
    "entry": [
        {
            "id": "8856996819413533",
            "changes": [
                {
                    "value": {
                        "messaging_product": "whatsapp",
                        "metadata": {
                            "display_phone_number": "16505553333",
                            "phone_number_id": "<PHONE_NUMBER_ID>"
                        },
                        "contacts": [
                            {
                                "profile": {
                                    "name": "<CONTACT_NAME>"
                                },
                                "wa_id": "<WA_ID>"
                            }
                        ],
                        "messages": [
                            {
                                "from": "<FROM_PHONE_NUMBER>",
                                "id": "wamid.id",
                                "timestamp": "<TIMESTAMP>",
                                "type": "image",
                                "image": {
                                    "caption": "This is a caption",
                                    "mime_type": "image/jpeg",
                                    "sha256": "81d3bd8a8db4868c9520ed47186e8b7c5789e61ff79f7f834be6950b808a90d3",
                                    "id": "2754859441498128"
                                }
                            }
                        ]
                    },
                    "field": "messages"
                }
            ]
        }
    ]
}

Received Callback from a Quick Reply Button Click#

{
    "object": "whatsapp_business_account",
    "entry": [
        {
            "id": "8856996819413533",
            "changes": [
                {
                    "value": {
                        "messaging_product": "whatsapp",
                        "metadata": {
                            "display_phone_number": "16505553333",
                            "phone_number_id": "27681414235104944"
                        },
                        "contacts": [
                            {
                                "profile": {
                                    "name": "Kerry Fisher"
                                },
                                "wa_id": "16315551234"
                            }
                        ],
                        "messages": [
                            {
                                "context": {
                                    "from": "16505553333",
                                    "id": "wamid.gBGGFlCGg0cvAgkLFm4e9tICiTI"
                                },
                                "from": "16315551234",
                                "id": "wamid.ABGGFlCGg0cvAgo-sHWxBA2VFD_S",
                                "timestamp": "1603087229",
                                "type": "button",
                                "button": {
                                    "text": "No",
                                    "payload": "No-Button-Payload"
                                }
                            }
                        ]
                    },
                    "field": "messages"
                }
            ]
        }
    ]
}
View Complete Webhook documentation
Modified at 2025-11-20 11:00:33
Previous
Send Interactive Reply Message
Next
Received Text Message
Built with