WhatsApp Webhook: Inbound Messages & Delivery Events
A WhatsApp webhook connects messaging activity back to your application. After your backend sends a message, its delivery state can change later. A customer can also send a new message to your WhatsApp Business number. In both cases, your application needs a way to receive that event and decide what happens next.
With MoceanAPI, these two flows can be viewed simply:
Outbound message → delivery event → webhook → application
and:
Customer message → inbound webhook → application
The important distinction is that a webhook is an event-delivery mechanism. It sends relevant messaging information to your endpoint; it is not the workflow engine that updates orders, creates support tickets or changes CRM records. Those actions remain under the control of your own application.
What Is a WhatsApp Webhook?
A WhatsApp webhook is an HTTP event-delivery mechanism that allows MoceanAPI to send inbound WhatsApp message information or later delivery events to an application endpoint.
That differs from a normal API request.
When your application calls an API, it starts the interaction:
application → API request → response
With a webhook, an event happens later and the information comes back to your application:
WhatsApp activity → MoceanAPI → your webhook endpoint
This matters because many messaging events are asynchronous. Your application does not know exactly when a recipient will receive or read a message, and it does not know when a customer will send a reply. Instead of continuously asking for changes, your backend can process the relevant event when it arrives.
MoceanAPI currently documents both delivery-status events and inbound WhatsApp messages through its WhatsApp API reference.
Delivery event vs inbound message
These are related, but they solve different problems.
A delivery event begins with an outbound message that already exists:
application sends message → message lifecycle changes → delivery event reaches backend
An inbound message begins with the WhatsApp user:
customer sends message → WhatsApp → MoceanAPI → inbound webhook → backend
Keeping these two event types separate makes implementation easier. Delivery events help your application understand what happened to a message it sent. Inbound events tell your application that the customer has sent something back.
How WhatsApp API Webhook Events Reach Your Backend
A practical WhatsApp API webhook architecture looks like this:
WhatsApp activity
→ MoceanAPI
→ configured business endpoint
→ webhook handler
→ application processing
Your webhook handler should focus on receiving and interpreting the event rather than containing every piece of business logic.
Conceptually, it should:
- receive the documented request;
- parse the relevant event information;
- identify the message or event;
- correlate it with existing application context where necessary;
- pass validated information to your business logic;
- record useful processing context;
- return whatever response the current API documentation requires.
The last point is deliberately documentation-dependent. The current WhatsApp reference reviewed for this article does not clearly establish a separate WhatsApp-specific acknowledgement, retry schedule or redelivery contract, so your implementation should follow the latest MoceanAPI WhatsApp API documentation rather than assuming behaviour from other webhook systems.
A webhook also does not automatically update your CRM, create a ticket, assign an agent or trigger an order-management workflow. Your application receives the event and decides whether any of those actions should happen.
WhatsApp Webhook Setup: A Practical Checklist
A good WhatsApp webhook setup starts with the application rather than with a copied payload.
1. Prepare a server-side endpoint
Create a backend route or handler that can receive the current documented webhook request. Webhook processing belongs in an appropriate server-side environment rather than exposed frontend code.
2. Make the endpoint reachable
The endpoint must be reachable by the service delivering the event. Use HTTPS as standard backend security practice.
3. Configure the correct event destination
For outbound WhatsApp messages, current MoceanAPI documentation includes the optional mocean-event-url parameter as the webhook destination for delivery events. A successful outbound request currently returns HTTP 202 and a message_id.
Do not assume that inbound-message callbacks are configured through the same parameter. Current documentation shows the inbound WhatsApp webhook structure and an example inbound endpoint, but the configuration mechanism should be checked in the latest documentation or with MoceanAPI support rather than inferred.
4. Parse the current event format
Read only the information your application needs. Avoid building your implementation from an old copied JSON example.
5. Add correlation logic
For delivery events, connect the event to the original outbound message and, where useful, to your own customer, order, case or transaction record.
6. Add operational logging
Record enough context to troubleshoot failures without placing credentials or unnecessary sensitive information in logs.
7. Handle errors defensively
Unexpected data should not cause unsafe business actions or bring down the entire processing path.
8. Test both event directions
Test:
outbound message → delivery event
and:
customer message → inbound event
These validate different parts of the integration.
How Delivery-Status Events Work
The outbound lifecycle can be reduced to six steps:
send request
→ message ID returned
→ delivery state changes later
→ delivery event reaches webhook
→ backend correlates the event
→ application state is updated
MoceanAPI currently returns a message_id when a WhatsApp send request succeeds. Delivery-event payloads also contain the message ID associated with the original transaction, giving the application a practical correlation point.
This distinction is important:
API request accepted ≠ sent ≠ delivered ≠ read
A successful API request tells you that the request has been accepted at that stage. It does not mean the recipient has already received or read the message.
Understanding WhatsApp Message Delivery Status
Current MoceanAPI documentation lists four meta_delivery_status values for WhatsApp message delivery status:
Status | Practical meaning |
sent | The message has reached the documented sent stage |
delivered | A later delivery state has been reported |
read | The message has reached the documented read state where applicable |
failed | A failure state has been reported |
These states should be treated as lifecycle information, not as guarantees about timing or application outcomes.
sent
sent is a documented message-lifecycle state.
Do not treat it as confirmation that the recipient has received the message. MoceanAPI’s current support guidance, for example, notes that a user who has blocked the business can result in a sent status without a later delivered status.
delivered
delivered represents a later delivery state.
It should not be turned into an SLA or timing guarantee. Your application can record the state, but it should not assume a particular delivery time based solely on the webhook status.
read
read is the documented read state where applicable.
There are two important implementation nuances in the current documentation. If the recipient has disabled WhatsApp read receipts, the read status will not be returned. The documentation also states that if the user reads the message immediately, WhatsApp may combine the delivered and read transition, meaning a separate delivered webhook may not be observed before read.
That is why developers should not hard-code the assumption that every message must always produce:
sent → delivered → read
as three separately observed events.
failed
failed is a documented failure state.
Current delivery events can include Meta-originated error information. Your application can inspect the information that is available, record the failure and decide what operational action is appropriate. Do not build a universal list of failure causes into your application based only on one example.
Why Message ID Correlation Matters
One of the most useful webhook design patterns is:
outbound send
→ message ID
→ store relevant reference
→ delivery event
→ match message ID
→ find business context
A delivery event becomes far more useful when your backend knows what the message represents.
For example, the same WhatsApp integration might send:
- an order update;
- an appointment reminder;
- a verification-related notification;
- a support-case update;
- an account alert.
The webhook tells you about the messaging event. Your own stored context tells you which business process that event belongs to.
An application may therefore retain information such as:
- MoceanAPI message ID;
- internal communication reference;
- customer or account reference;
- order, case or workflow reference;
- original send timestamp;
- last known delivery state;
- event-processing timestamp.
There is no need to prescribe one database schema. The objective is simply to preserve enough context for the application to relate an asynchronous event back to something meaningful.
How to Receive WhatsApp Messages Through the API
The whatsapp api receive message problem follows the other direction:
customer sends message
→ WhatsApp
→ MoceanAPI
→ inbound webhook
→ backend
→ application processing
Current MoceanAPI documentation lists inbound content types including text, audio, documents, video, images, stickers, button responses, reactions, interactive button responses, interactive list responses and order content. The inbound message resource also includes identifiers and contextual information that an application can use when processing a message.
The exact payload should remain in the API documentation rather than being copied into an evergreen article.
Conceptually, your backend may need to understand:
- who sent the message;
- which WhatsApp business destination received it;
- the message or content type;
- the message identifier;
- reply or interaction context where applicable;
- media references when the content contains media.
MoceanAPI’s current documentation also reflects the newer username and Business Scoped User ID model. Where a user’s phone number is unavailable, BSUID-related identifiers can be relevant to identifying that user in the business messaging context.
What Your Backend Does With an Inbound Message
Receiving the webhook is only the transport step.
After the event is parsed, your application might:
- store relevant message content;
- associate it with a customer or account;
- connect it to an order, case or workflow;
- notify another internal service;
- route it through business logic;
- prepare an appropriate response;
- retrieve media when necessary.
These are actions performed by the business application or connected systems. They are not automatic MoceanAPI workflow features.
Inbound messaging does not, by itself, mean that MoceanAPI is providing a shared inbox, helpdesk, live-agent dashboard, CRM synchronisation system, lead-routing engine, workflow builder or chatbot builder.
MoceanAPI delivers documented messaging information. Your application controls what that information causes your business systems to do.
Handling Inbound Media
When a customer sends supported media, the inbound event does not need to become your permanent file-management system. Current MoceanAPI documentation exposes a media reference for supported inbound audio, document, video, image and sticker content and provides separate media-download functionality.
The conceptual flow is:
inbound media event
→ media reference received
→ application uses documented media functionality
→ media is processed or stored as required
What happens after retrieval belongs to your application. You may need to associate the file with a customer record, apply your own security controls or store it in your own infrastructure. Exact download parameters, media limits and response details should be taken from the current API reference rather than duplicated here.
WhatsApp Webhook Example
A useful WhatsApp webhook example should show the application hand-off rather than burying the reader in JSON.
Example 1: Outbound order update
Order status changes
→ backend sends WhatsApp update
→ returned message ID is stored
→ delivery event arrives
→ webhook handler receives it
→ backend matches the message ID
→ internal communication status is updated
The final update is application behaviour. MoceanAPI delivers the messaging event; it does not manage the order record.
Example 2: Customer reply
Customer replies on WhatsApp
→ inbound webhook reaches backend
→ backend reads message context
→ customer/application context is identified
→ application stores, routes or processes the message
Again, the webhook transports the event. The business system decides whether that message should update a case, notify a team, initiate another process or receive a response.
Minimal processing pattern
Pseudocode is enough to illustrate the architecture:
receive webhook
parse documented event
identify event or message
correlate with application context
validate required information
process business action
respond according to current API requirements
This is deliberately not runnable MoceanAPI code. Exact fields and response behaviour should come from the latest API reference.
Process Webhook Events Safely
Separate transport from business logic
A useful design boundary is:
webhook handler → validated event → application service/business logic
The webhook handler receives and interprets the event. Your application logic decides whether that event should update an order, mark a notification, create an internal alert or perform another action.
Process only the information you need
Avoid tightly coupling your application to every property in a webhook payload. Use the fields required for your use case and keep implementation-specific schemas in your code and technical documentation.
Treat event receipt and business success separately
Receiving an HTTP event successfully does not necessarily mean the downstream business operation also succeeded.
For example, your webhook may successfully receive a delivered event while an internal database update fails. Those are two separate processing concerns and should be monitored accordingly.
Webhook Security and Reliability
Webhook endpoints are part of your backend attack surface, so ordinary server-side security practices still matter.
Use HTTPS, validate expected input, parse defensively, protect credentials, avoid unnecessary sensitive data in logs and monitor processing failures. High-impact business actions should happen only after the information your application requires has been validated.
Design for safe repeated processing
A useful application-level principle is:
Design webhook processing so that the same logical event does not accidentally cause the same business action multiple times.
For example, repeated processing should not create two orders or trigger the same internal notification twice.
This is an idempotency design recommendation. It is not a claim that MoceanAPI retries WhatsApp webhooks in a particular way.
Do not rely on guaranteed ordering
Unless current official documentation explicitly guarantees ordering, avoid designing your application around the assumption that every event must always be observed in one rigid sequence.
The read behaviour documented above is already a practical reason not to assume that delivered will always be observed separately before read.
The current WhatsApp documentation reviewed for this article does not establish a fixed retry count, retry schedule, exactly-once guarantee, at-least-once guarantee, webhook SLA, signature mechanism, HMAC header or ordering guarantee. Those behaviours should not be invented.
How to Test Your WhatsApp Webhook
Test delivery events
- Send an appropriate test WhatsApp message.
- Retain the returned message ID.
- Receive a later delivery event.
- Confirm your backend can parse it.
- Match the event to the original message.
- Confirm the intended internal state update.
MoceanAPI also documents a WhatsApp sandbox for testing sending and receiving with configured test numbers and trial templates.
Test inbound messages
- Send an appropriate message from a test WhatsApp user.
- Confirm the inbound event reaches your backend.
- Inspect it against the current documented format.
- Identify the sender and relevant application context.
- Confirm that your intended processing path runs correctly.
Test failure paths
Your application should also be tested against:
- malformed or unexpected input;
- an unknown message ID;
- a failed delivery event;
- internal processing errors;
- repeated logical processing.
Do not build tests around an assumed MoceanAPI retry mechanism unless the current documentation explicitly documents one.
Common WhatsApp Webhook Mistakes
- Treating API acceptance as final delivery. A successful send response and a later delivered or read event represent different stages.
- Discarding the message ID too early. If your application needs later delivery correlation, retaining the relevant identifier makes the event useful.
- Ignoring failed events. Define how your application records and investigates failures.
- Assuming every lifecycle is sent → delivered → read. Read receipts can be disabled, and current documentation notes that an immediately read message may not produce a separately observed delivered event.
- Assuming a webhook updates business systems automatically. Your application performs CRM, order, case or workflow updates.
- Treating inbound webhooks as a shared inbox. Receiving customer-message data is not the same as providing an agent interface.
- Copying old webhook payload examples. Use the current API reference when implementing fields and schemas.
- Assuming undocumented retries or guaranteed ordering. Design defensively without inventing provider behaviour.
- Triggering duplicate or sensitive business actions without safeguards. Validate input, protect application state and keep operational logging appropriate.
Build the Event-Handling Layer Around Your Application
A WhatsApp webhook gives your backend a return path for activity that happens after or outside the original API request.
For outbound messaging:
send → message ID → delivery event → correlate → update application state
For inbound messaging:
customer message → webhook → identify context → application action
The central responsibility boundary stays the same: MoceanAPI provides the programmable WhatsApp messaging and event layer, while your application controls the surrounding business workflow.
Review the current MoceanAPI WhatsApp API documentation for the latest inbound-event, delivery-status and webhook implementation details.
For the broader product capabilities, explore the MoceanAPI WhatsApp API.
Share this article :
