Your bot can send messages but never receives one. If you've connected WhatsApp to a self-hosted agent, that's the most likely first failure, and it has nothing to do with the AI.
It's a webhook problem. Specifically one of four, and we'll go through each. We hit a version of this ourselves: a user reported that numbers connected through their own Meta app could send but never receive, because the signature on incoming webhooks didn't match what our hosted service was checking. We fixed it (more on that below). The lesson applies to anyone running their own setup.
This is part four of our WhatsApp series. Part one covered the general setup, part two grounded replies, part three lead qualification. This one is for the person with a terminal open.
Written by the ChatterMate team. We build an open-source AI support agent. We've marked what we verified against docs and our own issue tracker, and what we didn't.
What you're wiring up in a WhatsApp webhook setup
WhatsApp Cloud API is push-based. When a customer messages your number, Meta doesn't wait to be asked. It sends an HTTP request to a URL you gave it. That URL is your webhook. If nothing is listening, or the listener rejects the request, the message goes nowhere you can see.
So a WhatsApp webhook setup is really three links in a chain: Meta's app, a public address, and your server's willingness to accept what arrives.
For ChatterMate, the README says WhatsApp runs on the Business Cloud API through your own Meta app, with templates, media and 24-hour session handling, and that WhatsApp shares one inbox with the web widget. The self-host route installs with the chattermate-deploy CLI or Docker Compose, which brings up Postgres, Redis, the backend, the frontend and a worker. None of that documentation walks through the WhatsApp callback URL for a self-hosted install. So we'll say what Meta requires, what we know from our own tracker, and where you'll need to read your own instance's settings.
Problem one: Meta can't reach you
Your laptop on localhost is invisible to Meta. The callback must be a public HTTPS address.
Meta's webhook documentation is blunt about it: HTTPS with a valid certificate, and self-signed certificates aren't supported. That rules out the quick "I'll point it at my home server with a certificate I made" approach. A real certificate from Let's Encrypt or your reverse proxy works fine.
Two more constraints before you start. Each Meta app gets one webhook endpoint. And the endpoint has to answer fast. One third-party write-up says "within a few seconds" without giving a number, so we won't invent one. Treat anything slow in your request path as a risk.
Practical advice:
- Put a reverse proxy (nginx, Caddy, Traefik) in front, terminating TLS with a real certificate.
- For testing before you have a domain, a tunnel service gives you a public HTTPS URL pointing at your machine. Webhook Relay's guide covers the idea. Tunnel URLs often change on restart, so every restart means re-saving the callback in Meta. Annoying, not mysterious.
- Check the path from outside your network. Curl your own public URL from a phone on mobile data. If you can't reach it, neither can Meta.
Problem two: the verification handshake fails
When you save the callback URL, Meta sends a GET request first. It carries three query parameters: hub.mode, hub.verify_token and hub.challenge. Your server checks that the token matches the one you configured, then returns the challenge value with a 200.
Two details trip people up.
The verify token is something you invent. It's a string you choose, and it exists only for this handshake. It is not your app secret and not your access token. Mixing those up is a classic.
Return the challenge raw. Not wrapped in JSON, not in quotes. One guide warns that a JSON-wrapped challenge fails verification.
Why this matters for self-hosting: you now control both ends. On a hosted service, someone else configured the token. On your own server, you set it, so the value in your config and the value in Meta's dashboard must match, character for character. A trailing space from a copy-paste is depressingly common.
In our own case, the hosted version originally used a single server-wide verify token that customers couldn't see, so those customers couldn't finish Meta's setup. The fix gave each account its own token and showed the callback address and token on the connection card. We haven't walked through every screen of that flow on a self-hosted deployment, so read your instance's WhatsApp settings rather than trusting our description.
Problem three: the signature doesn't match
This is the one that bit us, so it gets the most space.
Every event Meta posts carries an X-Hub-Signature-256 header, formatted sha256=<hex>. It's an HMAC-SHA256 of the raw request body, keyed with your app secret, which lives in your Meta app under App settings, then Basic. A correct server recomputes the HMAC over the exact bytes it received and compares in constant time. If they differ, it rejects the request.
Rejecting is the right behavior. Without it, anyone who finds your webhook URL could post fake messages and have your agent answer them. But rejection is also why a wrong secret looks like silence. Meta sends, your server says no, and your inbox stays empty.
The failure modes we've seen or can reason about:
- Wrong secret. You pasted the access token, or the verify token, or the secret from a different Meta app.
- Body modified before checking. A framework that parses JSON and re-serializes it changes the bytes. The HMAC has to run over the raw body.
- Several apps, one server. This was our case. Per our tracker, webhooks for a number in a customer's own Meta app are signed with that app's secret. A server that only knows its own secret rejects every one of them.
The maintainer's reply on that issue explains the design choice. The first idea, trying every customer's secret against the shared endpoint, was dropped because it would let someone sign a payload with their own secret and claim another customer's number. So each account got its own callback address. Meta's per-number callback is used when Meta accepts it, and if not, the card shows the URL and verify token to paste in manually. An optional app secret field was added, and the secret is checked with Meta at connection time.
Run one Meta app with one number on your own server and you're in the easy case: one secret, one endpoint. Run several and you'll want a distinct address for each.
Problem four: you verified, but nothing arrives
The handshake passed, the signature code is right, and the inbox is still empty. Usually you didn't subscribe to the right field.
After verification you subscribe the webhook to fields. For inbound messages that's messages. Skip it and you get no events. Delivery receipts (sent, delivered, read) come on the same URL, in a statuses array rather than as messages, so a handler that assumes every POST is a customer message will choke on them.
Other reasons for silence, in the order we'd rule them out:
- The number isn't connected to the app you configured. Check the phone number ID.
- You're in test mode. Meta's free test number lets you try things without registering a real one, but it only talks to numbers you've added as recipients.
- The customer's last message was over 24 hours ago and you're expecting a free-form reply. That's a sending rule, not a receiving one, but it gets reported as "the bot is broken." More in part one.
- A worker isn't running. The README says background workers must run separately or jobs stay pending. That note covers the knowledge, ticket investigator and CRM sync workers, so it may not touch message receipt, but if answers are slow to appear, read your logs before blaming Meta.
A debugging order that saves an afternoon
Work from the outside in. Don't touch the AI settings until the plumbing is proven.
- Reachability. Curl your public HTTPS URL from outside your network. Valid certificate, no redirect surprises.
- Handshake. Save the callback in Meta. If it fails, compare the verify token in both places and look at your server log for the GET request and what you returned.
- Subscription. Confirm
messagesis subscribed. - A message from a personal phone. Watch the server log. No POST arriving means Meta-side or reachability. A POST that arrives with nothing in the inbox means look at signature checking.
- Only then look at the agent's behavior.
Logs decide everything here. The README lists a logs command for chattermate-deploy, and Docker Compose gives you the usual docker compose logs. Run them in a second window while you send the test message. Thirty seconds of watching a request arrive, or not, beats an hour of guessing.
The privacy upside, and its limit
People pick self-hosting for control. With the README's stack, conversations sit in your own Postgres and attachments go to S3 storage you configure. That's real control, and our note on chatbot data retention covers how long to keep it.
The limit is easy to forget. WhatsApp traffic still passes through Meta. Self-hosting your agent doesn't hide the channel from Meta, and if you use a hosted LLM, the text sent to it leaves your server too. You change who stores the data and where. You don't make the pipe invisible. If your compliance team cares, write that down plainly. The broader picture is in self-hosted AI chatbot.
What we haven't verified
Since you're about to run this on a real number:
- We found no public page documenting ChatterMate's WhatsApp callback path or the exact environment variables for it. The README points to
.env.examplefor the full variable list. Read it. - Our evidence for per-account callbacks and verify tokens comes from a closed issue about the hosted service. A self-hosted deployment may expose these differently.
- We haven't benchmarked webhook latency, and we don't quote a timeout for Meta's side.
If your install doesn't match this post, open an issue. That's how the app-secret fix happened.
Before you go live
Run through this once with a test number:
- Public HTTPS URL, real certificate, reachable from outside your network.
- Verify token identical in config and in Meta, no stray whitespace.
- App secret from the same Meta app as the number.
messagessubscribed.- One round-trip message, watched in the logs.
- Then read how to test an AI chatbot before anyone real writes in.
Next in this series: how ChatterMate compares to Instantly for WhatsApp automation. ChatterMate is open source and free to start, with 50 free AI replies a month, and you can self-host it: chattermate.chat.



