A webhook means Meta tells {{brand.name}} by itself when something happens. The panel doesn't keep asking Meta "any new messages?"; the moment someone sends you a DM, Meta pushes a notification to us and the message lands in your inbox within seconds. This article explains how that path is set up and what happens when it breaks.
What it is for
Without a webhook the inbox stays empty. All of these events arrive this way:
New DMs and WhatsApp messages
Button taps and quick-reply choices
Read receipts and reactions
New comments, live video comments and mentions
The source of chats that start from an ad or a tagged link
Your automations are triggered by these events too: a keyword trigger only runs once a message reaches the panel.
How the subscription is set up
The moment you connect an account, the panel tells Meta in the background: "send me this account's events." That is the subscription, and where it is made depends on the channel:
An account connected with Instagram — the subscription is made on the Instagram account directly.
An account connected through a Facebook Page — the subscription is made on the Page the account belongs to. If the Page subscription fails, no message arrives at all.
A WhatsApp number — the subscription belongs not to the number but to the WhatsApp business account it sits in. So the events of every number in that business account flow through the same subscription.
✅ That is why, if you have two numbers in the same WhatsApp business account and disconnect one, the other keeps working: the shared subscription is removed only when the last number leaves.
If the subscription fails while connecting, the account stays connected but its state becomes error, and the card says "Webhook subscription failed; messages may not arrive." In that case a Renew webhook subscription button appears on the card.
How a message reaches the panel
The order is:
Someone writes to you. Instagram or WhatsApp receives the message.
Meta sends us a notification. It contains the account ID, the sender and the message.
The panel verifies the signature. Every notification is signed by Meta; a request whose signature doesn't match is refused. That makes it impossible to forge a request in Meta's name.
The notification is written to a durable queue. Meta gets an immediate "received" response, and processing starts afterwards. That separation matters: even when the panel is busy, Meta is never kept waiting and no notification is lost.
The queue is processed. The message is matched to a contact, added to the conversation and shown in the inbox.
Automations run. The flow the message triggers answers right away.
If something goes temporarily wrong during processing, the notification is retried, with growing gaps, up to 8 times. So a brief hiccup doesn't lose the message; it arrives a little later.
⚠️ Note: If the same notification arrives twice, it isn't processed twice and the same message isn't added to the conversation twice. Meta sometimes repeats a notification; this protection exists for that.
The security side
Signature checks. A request with an invalid signature can do nothing; it is refused.
Old notifications are rejected. The notification's own timestamp is checked; a body older than 24 hours is not processed even if it is resent. That defeats any attempt to record an old notification and replay it later.
A single endpoint. Every account receives notifications at one secure address; there is no per-account address and no technical setting is ever asked of you.
Is there anything for you to do
Normally no. The subscription is set up while connecting and the system maintains it. You only step in in two cases:
The card is in the error state and the reason is the subscription: press Renew webhook subscription. If it succeeds, the card returns to Active and says "Webhook subscription renewed".
If renewing also fails, reconnect the account; usually the problem isn't the subscription but an invalid token or missing permissions.
A concrete example
You sell spare parts and have just connected your Instagram account. The card looks Active, but when you ask a friend for a test DM nothing arrives. You open the connection page and look at the card: the state is error, and under it: "Webhook subscription failed; messages may not arrive." You press Renew webhook subscription, get the "Webhook subscription renewed" message, and ask your friend to write again. This time the message arrives in seconds. The Last event line on the card now says "just now" — that line is the fastest proof that the subscription works.
Common mistakes and how to fix them
Deleting and reconnecting the account because messages don't arrive. Try Renew webhook subscription first; it is usually enough and your data stays in place.
Writing to yourself from your own account. A message you send from your own account doesn't behave like a customer message in the inbox. Use another account to test.
Ignoring the "Last event" line. It tells you when the most recent event arrived; it is the quickest way to see whether the subscription really works.
Granting incomplete Page permissions on the Facebook path. Without the Page subscription permission, no subscription can be made at all; the account looks connected but stays silent.
Fixing the subscription and forgetting the approval problem. Even with a working subscription, without Meta's approval only messages from people with a role on the app are delivered; see The Meta app and App Review.