WhatsApp API Webhook Integration Requirements

WhatsApp API Webhook Integration Requirements

The main WhatsApp API webhook integration requirements are a Meta Business account, a WhatsApp Business Account (WABA), a registered business phone number, an access token, a publicly reachable HTTPS endpoint, and server-side code that can verify and process WhatsApp event notifications. You also need secure webhook handling, message-status logic, retry protection, data-storage controls, and a clear plan for templates, consent and the 24-hour customer-service window.

A webhook is the part of the WhatsApp API integration that receives events from Meta. Instead of repeatedly asking WhatsApp whether a message was delivered or whether a customer replied, your application receives a notification when that event occurs.

For an Indian NGO, D2C brand, school, clinic or small business, the webhook may connect WhatsApp to a CRM, helpdesk, donation system, appointment platform, order-management system or internal dashboard. The quality of this connection depends less on the WhatsApp chat screen and more on the backend design behind it.

What a WhatsApp API Webhook Does

The WhatsApp Cloud API uses webhooks to notify your application about changes and activity associated with your WhatsApp Business Account and phone number.

Typical events include:

• An inbound customer message
• A message delivered to the recipient
• A message read by the recipient
• A message that failed to send
• A customer replying to a template or service message
• A button, list or interactive reply
• A media message such as an image, document, audio file or video
• A customer sharing contact or location information
• Changes related to message errors or account events, depending on the subscribed webhook fields

A normal API request sends information from your system to Meta. For example, your order system may call the WhatsApp API to send an order-confirmation template.

A webhook works in the opposite direction. Meta calls your server and tells it that a customer has replied or that a previously sent message has changed status.

A basic flow looks like this:

1. A customer sends a message to your WhatsApp number.
2. Meta receives and processes the message.
3. Meta sends a webhook request to your configured endpoint.
4. Your server verifies that the request is genuine.
5. Your server stores the event or places it in a queue.
6. Your application updates the CRM, order record or support dashboard.
7. If a response is required, your system sends a separate API request to WhatsApp.

The webhook does not itself send a reply. It informs your application that something happened. Your application decides what to do next and uses the WhatsApp API for outgoing messages.

Webhooks and API integration are different

These terms are often used together, but they are not interchangeable.

A dependable implementation usually needs all of these layers, not only a URL that receives JSON.

Meta and WhatsApp Business Account Requirements

Before development begins, the business needs the correct Meta assets and permissions. The exact screens and approval steps can change, so the current Meta Business documentation should be checked during setup.

Meta Business account

You generally need a Meta Business portfolio or business account to manage the WhatsApp Business Account, users, phone numbers and system access.

The business information should be consistent across the relevant records. Differences in legal name, website, phone details and business documents can create delays during verification or review.

For an Indian company, NGO or educational institution, keep commonly requested information available, such as:

• Legal entity name
• Registered business address
• Website or public organisation page
• Business phone number
• Tax or registration details where applicable
• Authorised administrator access
• Brand name and customer-facing business description

A sole proprietor, trust, society, Section 8 company, private limited company or partnership may have different supporting documents. The person setting up the account should have authority to administer the organisation’s Meta assets.

WhatsApp Business Account

The WABA is the account under which the phone number, display name, templates and messaging activity are managed. It is not the same as a regular WhatsApp Business mobile application account.

You should decide whether to use:

• Meta’s WhatsApp Cloud API directly
• A WhatsApp Business Solution Provider, often called a BSP
• A CRM or helpdesk platform that includes WhatsApp API access

Using a BSP can reduce some setup work and provide a shared inbox, templates or support tools. It can also introduce provider-specific APIs, charges, account dependencies and limitations. Ask the provider whether you receive direct access to webhook payloads, message IDs, media, templates and delivery statuses.

Business phone number

The phone number used for API onboarding needs to be planned carefully. Depending on the onboarding route and current Meta rules, a number may need to be available for API registration rather than being actively used in the consumer WhatsApp or WhatsApp Business application.

Do not move a number into production without confirming the migration consequences. You may need to consider:

• Whether the existing chat history will remain available
• Whether the number can continue using the mobile application
• Whether calls or SMS verification are possible
• Whether the number belongs to a current vendor account
• Whether the public display name matches your organisation’s identity
• Whether the number is used on printed materials, websites or Google Business Profile listings

A separate number is often easier for a new support or notification channel, but the right choice depends on existing customer behaviour.

Access tokens and permissions

Your server needs an access token to call the WhatsApp API. For production, use a suitable system-user or business-managed token rather than placing a temporary developer token in application code.

The implementation may require permissions related to WhatsApp business management and messaging. The exact permission names and approval process depend on the Meta setup and the operation being performed.

Access must be limited to the people and services that need it. Store tokens in environment variables or a managed secrets service. Do not put them in JavaScript sent to browsers, public Git repositories, screenshots, spreadsheets or chat messages.

Technical WhatsApp API Webhook Integration Requirements

The webhook endpoint is a public web address that Meta can reach from the internet. It is usually a route such as:

https://yourdomain.in/webhooks/whatsapp

The path can be different, but it should be dedicated to webhook traffic and protected like any other production API.

Public HTTPS endpoint

The endpoint should:

• Use HTTPS with a valid certificate
• Be reachable from Meta’s servers without a VPN or office-only firewall
• Accept the HTTP methods required for verification and event delivery
• Handle JSON request bodies
• Return an appropriate HTTP response quickly
• Remain available during the hours when customers may message
• Avoid redirects that may interfere with verification
• Use a domain controlled by the business or its technology provider

A locally running server on a Pune office network cannot normally receive production webhooks unless it is exposed through a properly secured public gateway. Temporary tunnelling tools may help during development, but they should not automatically be treated as a production architecture.

Verification handshake

Webhook setup commonly includes a verification request from Meta. Your endpoint receives verification parameters, checks the verification token configured by your team, and returns the challenge value when the token matches.

The important controls are:

• Compare the received verification token with the server-side value
• Do not accept every token
• Return the challenge only after successful validation
• Log the result without recording unnecessary secrets
• Keep separate values for development, testing and production

The verification token is a shared setup value. It is not the same as the access token used to call the WhatsApp API.

POST event handling

After verification, Meta sends event notifications to the endpoint, usually as HTTP POST requests containing a JSON payload.

The payload can include nested objects for the business account, phone number, contacts, messages, statuses and errors. Your code should not assume that every event contains a customer text message.

For example:

• A status notification may contain a message ID but no message body.
• An image message may contain a media ID rather than a public image URL.
• A failed message may contain an error object.
• An interactive reply may use a button or list structure.
• A business-account event may not look like a normal inbound chat message.

The parser should identify the event type before attempting to read fields. Code that assumes messages[0].text.body exists will fail when the event is a delivery status, media message or error notification.

Signature validation

Webhook requests should be checked for authenticity using the signing mechanism supported by Meta, commonly based on the app secret and an X-Hub-Signature-256 header.

The usual pattern is:

1. Read the raw request body before a JSON parser changes it.
2. Calculate the expected signature using the configured app secret.
3. Compare signatures using a timing-safe method.
4. Reject requests with a missing or invalid signature.
5. Parse and process only validated payloads.

The exact implementation depends on your programming language and framework. Express, Laravel, Django, Spring Boot, WordPress plugins and serverless functions handle raw request bodies differently, so the developer must verify that signature validation is being performed on the original bytes.

Do not rely only on an unknown URL, an IP allowlist or a user-agent string as proof that a request came from Meta.

Event Notifications Your System Should Handle

A webhook integration is useful only when the application converts events into business actions.

Inbound customer messages

Your system should identify:

• The WhatsApp phone number that received the message
• The customer’s WhatsApp identifier and display information where provided
• The message ID
• The message type
• The message timestamp
• The text, interactive selection or media reference
• Any relevant context, such as a reply to an earlier message

A customer may send text, an image of a document, an audio note, a video, a location, a contact card or an interactive response. A school may receive a fee screenshot, a clinic may receive a prescription image, and an NGO may receive a donation query with an attachment. These cases need different storage and staff workflows.

Delivery and read statuses

Outgoing message status events are essential for support and reporting. Your database may need to distinguish between:

• Accepted by the API
• Sent
• Delivered
• Read
• Failed

Do not treat an API success response as proof that the customer received the message. An API response generally confirms that the request was accepted for processing. Later webhook events provide the operational status.

Store the WhatsApp message ID returned for outgoing messages. Use it to connect later status events to the correct order, ticket, appointment or campaign record.

Errors and failures

Your system should record failure information in a way that staff can understand. A generic “WhatsApp failed” message is not enough for troubleshooting.

Useful internal fields include:

• Message ID
• Recipient identifier
• Time of failure
• Template or message type
• Error code and text received
• Related business record
• Retry count
• Whether manual action is required

Some errors are temporary and may be retried. Others indicate an invalid recipient, a missing template, policy restrictions, a problem with permissions or a message outside the allowed conversation rules. Blindly retrying every error can create duplicate messages and additional failures.

Reliability, Queues and Duplicate Protection

A common developer mistake is to perform all business processing inside the webhook request. The server receives an event, calls the CRM, downloads media, sends an automated reply, writes several database records and only then responds to Meta.

This creates avoidable problems. If the CRM is slow, the webhook request remains open. If the application crashes after one operation but before another, the event may be processed incompletely. If Meta retries a request, the customer may receive duplicate replies.

A safer processing pattern

A practical production flow is:

1. Receive the request.
2. Validate the signature.
3. Check the basic payload structure.
4. Store the raw or suitably protected event record.
5. Place a job on a queue.
6. Return a successful response promptly.
7. Let a background worker perform CRM updates, media handling and business automation.

The queue may use a managed cloud service, Redis-based worker, database-backed job system or another reliable mechanism suitable for the application.

Idempotency

Webhook delivery can be repeated. Your application must assume that the same event may arrive more than once.

Use a unique event or message identifier where available. Before processing, check whether that identifier has already been handled. Database uniqueness constraints are useful because they protect against duplicates even when two workers process the same event at nearly the same time.

For outgoing automation, also create an internal idempotency rule. For example, an order-confirmation workflow should know that confirmation has already been sent for a particular order and event, rather than sending again simply because a webhook was repeated.

Retry and dead-letter handling

If a CRM is temporarily unavailable, the worker should retry with controlled backoff. If the event continues to fail, move it to a dead-letter or review queue.

Staff should be able to see:

• Which event failed
• Why it failed
• When the next retry will occur
• Whether it can be replayed safely
• Whether the customer needs a manual response

Monitoring should alert the team when the webhook endpoint receives no events for an unusually long period, when signature failures increase, or when the processing queue grows.

Templates, Consent and Indian Compliance

Webhook engineering cannot be separated from WhatsApp messaging rules. A technically correct integration can still create business or compliance problems if the message policy is not planned.

Template messages

Business-initiated messages generally need an approved WhatsApp message template when the conversation is outside the applicable customer-service window. Templates are created and managed through Meta or the selected provider.

Templates may be used for:

• Order confirmations
• Delivery updates
• Appointment reminders
• Payment acknowledgements
• Event registrations
• Donation receipts
• School notices
• Support follow-ups

Template content should match the declared purpose. Avoid writing a promotional message under a utility-style expectation. Keep variables controlled and validate values before sending. A blank customer name, unexpected currency symbol or unescaped product description can make a message look unreliable.

Template category rules, pricing and approval requirements can change. Check the current Meta documentation and your BSP’s commercial terms before planning a campaign.

The customer-service window

When a customer has recently initiated a conversation, your team may have more flexibility to respond with ordinary messages during the applicable customer-service window. Outside that window, an approved template may be required.

Your application should store the time of the customer’s most recent inbound message and use that information when choosing a response type. This should not be left to staff memory.

If the customer writes “I need help with my order,” the support system can reply in the open service conversation. If the business later wants to send a promotional message after the permitted period, it should use the appropriate approved template and follow opt-in requirements.

Consent and opt-out

Keep a record of how a person agreed to receive WhatsApp communication. Depending on the use case, this may be a website checkbox, a form, an event registration, a phone conversation recorded in a CRM or an existing customer-service interaction.

The record should ideally include:

• Customer identifier
• Purpose of communication
• Date and source of consent
• Brand or business name
• Type of messages permitted
• Opt-out or withdrawal status

Every promotional workflow should support a clear opt-out process. A customer replying “STOP” should not be routed only to an AI bot that ignores the request. The system should mark the customer appropriately and make the status visible to staff.

For Indian organisations, review the Digital Personal Data Protection Act and applicable rules as they become operational, along with contractual obligations and sector-specific requirements. Data minimisation, purpose limitation, access control, retention and deletion should be included in the design.

Clinics should be particularly careful with health-related information. Schools should control access to student and parent conversations. NGOs should protect donor details and beneficiary information. Do not send sensitive information in plain messages merely because the channel is convenient.

GST and provider charges

Meta, BSP and software-provider charges may involve different billing arrangements. Confirm whether invoices include GST, whether the provider is registered in India, and how taxes are shown on invoices.

If the business uses an Indian vendor for development or support, the vendor’s GST treatment and invoice structure should be confirmed before procurement. This is an accounting matter, but it affects the actual operating cost of an API integration.

Recommended Data Model and Security Controls

Before coding, define what your application will store. A small business does not need to retain every payload forever.

A practical model may include:

• Business account and phone-number identifiers
• Customer identifier and display name
• Conversation record
• Message ID and direction
• Message type and status
• Template name and language
• Related order, ticket, donation or appointment ID
• Media reference and controlled storage location
• Consent and opt-out status
• Timestamps
• Error details
• Processing status

Media handling

WhatsApp media is generally accessed through an API-mediated process rather than treating the webhook’s media identifier as a permanent public download URL. Your application may need to retrieve the media using authorised credentials, scan it, store it securely and apply a retention policy.

Do not put private documents in an open public folder. Use access-controlled object storage, short-lived download links where appropriate, virus scanning and role-based access.

Access control

Not every employee needs access to every conversation. A clinic receptionist may need appointment messages but not internal medical notes. A school coordinator may need parent communication but not financial exports.

Use:

• Separate admin and staff roles
• Two-factor authentication for administrators
• Audit logs for exports and deletions
• Restricted database access
• Secret rotation
• Encrypted backups
• Environment separation for development and production

Avoid copying customer messages into developer tickets or informal WhatsApp groups for debugging.

Retention and deletion

Decide how long the business needs to retain message records, media and logs. Retention may depend on accounting, customer-support, legal or sector needs.

Raw webhook payloads can contain more information than the business requires. Store only what supports a defined purpose, redact sensitive values in logs and delete old records according to an approved policy.

Testing and Production Checklist

Testing should cover more than a successful text message. Prepare test cases for the complete lifecycle.

Account and setup checklist

• Meta Business account is controlled by the organisation
• Correct WABA and phone number are selected
• Production business administrators are identified
• Access token is stored securely
• Required permissions are available
• Webhook subscription is connected to the correct WABA
• Display name and business profile are reviewed
• Templates are approved where needed
• A documented process exists for token rotation and staff access

Endpoint checklist

• HTTPS certificate is valid
• Verification handshake succeeds
• Invalid verification tokens are rejected
• Signature validation uses the raw request body
• Invalid signatures are rejected
• JSON payloads are parsed safely
• Unknown event types do not crash the endpoint
• The endpoint responds quickly
• Events are logged with correlation identifiers
• Duplicate events do not create duplicate records

Business-flow checklist

Test at least:

• Inbound text
• Inbound image or document
• Interactive button reply
• Outgoing template
• Delivery status
• Read status
• Failed message
• Customer opt-out
• Duplicate webhook delivery
• Temporary CRM outage
• Expired or invalid access token
• Missing message fields
• Multiple customers messaging simultaneously

The application should also handle a customer sending several messages quickly. Conversation ordering should use event timestamps and message IDs rather than relying only on the order in which background jobs finish.

Staging and go-live

Use a separate staging environment where practical. Test accounts, tokens, phone numbers and webhook URLs should be clearly separated from production.

Before go-live, document who handles:

• Failed messages
• Template rejection
• Customer complaints
• Token expiry
• Account review
• Server outage
• Data deletion requests
• Vendor escalation

A webhook is part of an operational system. Someone must own the alerts after the developer has completed the integration.

Cloud API, BSP or Existing Software

The right integration route depends on your team and workflow.

For a small clinic, an existing helpdesk may be sufficient. For a D2C brand with order updates, returns and agent assignment, custom middleware may be more appropriate. For an NGO handling registrations and reminders, a form, CRM and WhatsApp workflow may need careful consent mapping.

Do not select a provider only because it offers a low introductory price. Confirm ownership of the WABA and phone number, access to data, support responsibilities, message billing, template management and the process for leaving the platform.

Frequently Asked Questions

What is the minimum required for a WhatsApp API webhook integration?

At a basic level, you need a Meta Business setup, WhatsApp Business Account, registered phone number, appropriate access credentials, a webhook subscription and a public HTTPS endpoint. Production use also requires signature validation, database storage, duplicate protection and a plan for failures.

Can a webhook run on localhost?

Meta cannot normally reach a server that exists only on your laptop or private office network. A secure temporary tunnel can be useful during development, but production should use a reliable public HTTPS endpoint with proper monitoring and access controls.

Do I need to store the complete webhook payload?

Not always. Store the fields needed for support, reporting, compliance and business workflows, and retain raw payloads only when there is a clear reason. If raw data is retained, protect it and define how long it will remain available.

Why are delivery statuses important?

An API response usually indicates that a message request was accepted for processing, not that the customer read it. Delivery, read and failure webhook events let your CRM or support team distinguish between these states and take suitable action.

Can I send any reply after receiving a customer message?

The permitted response depends on the applicable customer-service window, message type and WhatsApp policies. Outside the relevant window, an approved template may be needed. Your integration should track the last customer message and avoid relying on manual timing.

Is a BSP required for WhatsApp API integration?

No single route is right for every business. A BSP can simplify onboarding and provide support tools, while direct Cloud API development gives more control. Compare account ownership, webhook access, data handling, support, integration limits and total charges before choosing.

Where to Start

Begin by documenting the business workflow before asking a developer to build the webhook. List the messages you will receive, the messages you will send, the system that should be updated, the staff who will respond and the information that must not be stored.

Then confirm the Meta account structure, phone-number plan, template needs, consent process and data-retention rules. Prepare a staging endpoint and test message-status events before connecting production automation.

For custom work, ask the development team to include signature validation, queue-based processing, idempotency, monitoring, access control and an error-replay process in the scope. Govindani Infotech can discuss the technical approach and provide the confirmed project pricing on WhatsApp.