---
title: "Connecting the WhatsApp Business Cloud API to a shared inbox"
canonical: https://aa-labs.co/blog/connecting-whatsapp-business-cloud-api-to-a-shared-inbox
author: A & A Labs
published: 2026-08-23
updated: 2026-08-23
category: Messaging
tags: [Laravel, WhatsApp API]
publisher: A & A Labs
reading_minutes: 2
---

# Connecting the WhatsApp Business Cloud API to a shared inbox

> Inbound WhatsApp messages arrive as signed webhooks from Meta. Acknowledge them within seconds, verify the signature, queue the work, and deduplicate on the platform message id — those four rules prevent almost every lost or duplicated message.

## Key takeaways

- Return 200 immediately and do the real work on a queue — Meta retries anything slow.
- Verify the X-Hub-Signature-256 HMAC before you parse the payload.
- Deduplicate on the platform message id; retries are normal, not exceptional.
- Route by phone number id, and quarantine anything you cannot route.

A shared inbox looks simple from the outside: a customer sends a WhatsApp message, an
agent sees it, an agent replies. The interesting part is everything between those steps.

## How an inbound message actually arrives

Meta does not hold messages for you to poll. It posts them to a webhook URL you
register, and it expects an answer quickly. If your endpoint is slow, Meta retries —
and a retry that you also handle slowly becomes two copies of the same message.

The rule that follows is not subtle: **acknowledge first, process later**.

```php
public function handle(Request $request): Response
{
    // Verify before parsing. An unsigned payload is not a message.
    abort_unless($this->signatureIsValid($request), 401);

    ProcessIncomingMessage::dispatch($request->all());

    return response()->noContent();  // 200, in milliseconds
}
```

## Verify the signature before you trust the payload

Meta signs each delivery with an HMAC over the raw request body, keyed by your app
secret. Verify it against the *raw* body — not the re-encoded array, whose key order
and escaping will not match.

## Deduplicate on the platform message id

Every message carries an id that is stable across retries. Store it, make it unique,
and let the database reject the second copy. This is much more reliable than trying
to guess whether a payload is a duplicate by comparing content and timestamps.

## Quarantine what you cannot route

In a multi-tenant inbox, an inbound message is matched to a tenant by the phone number
id it arrived on. If no active channel matches, the wrong answer is to file it under
the first tenant you find; the right answer is to record it somewhere an operator can
inspect and replay it.

That last one is the difference between "we lost a customer's message" and "we found
a misconfigured channel."

## Frequently asked questions

### How fast does a WhatsApp webhook need to respond?

Acknowledge within a few seconds. Meta treats a slow or failed response as a delivery failure and retries, so any real work — media downloads, database writes, broadcasts — belongs on a queue behind an immediate 200.

### Why do duplicate WhatsApp messages appear in an inbox?

Almost always because retries are not deduplicated. Meta resends a delivery it believes failed; if the handler has no unique constraint on the platform message id, the retry is stored a second time.

### Can one app handle WhatsApp numbers for many businesses?

Yes. Each business connects its own number and access token, and inbound messages are routed to a tenant by the phone number id they arrived on. Credentials must be stored encrypted and scoped per tenant.


---

Published by A & A Labs · https://aa-labs.co/blog/connecting-whatsapp-business-cloud-api-to-a-shared-inbox