Facebook Webhooks Setup: The App Review Blocker Most Developers Miss
Your app can have a perfect privacy policy, a flawless screencast, and every permission field correctly filled — and still get rejected. If your webhook endpoint is missing, unreachable, or returns an error during the review, Meta cannot verify that subscription-based permissions actually work in your application.
pages_messaging, instagram_business_manage_messages, lead_retrieval, and others — Meta's reviewers actively test your webhook endpoint during the review process. A timeout, a 404, or a failed verification handshake produces the same result: the submission is rejected, the review window resets, and if you are close to the 30-day expiry, the entire request closes and must be rebuilt from scratch.
Why Webhooks Are an App Review Gate
What webhooks do
Webhooks are HTTPS callback URLs you register with Meta. When a subscribed event occurs — a message received, a lead submitted, a comment posted — Meta sends an HTTP POST to your endpoint in real time. For subscription-based permissions, there is no alternative delivery path. Without a working endpoint, event-based permissions have no way to be verified as functional.
What reviewers actually test
During App Review, Meta's reviewers do not just read your documentation and watch your screencast. For subscription-based permissions, they trigger real events and expect your webhook to receive and acknowledge them correctly. If the endpoint is unreachable, returns an error, or does not process the event, the permission is marked as unverifiable and the submission is rejected.
The cost when it fails
A webhook failure triggers the same rejection outcome as a bad screencast or a broken privacy policy URL. The 30-day resubmission window resets to zero. If the rejection happens near the window expiry, the App Review request closes entirely and must be recreated — with a new screencast, new justifications, and another full wait. Each failed cycle costs weeks.
Permissions That Require Working Webhooks
The following permissions require a publicly accessible, verified webhook endpoint as part of App Review. This is not an exhaustive list — Meta may require webhooks for additional permissions depending on your app type and use case.
messages event. No working webhook means no verifiable permission — the submission fails regardless of what is shown in the screencast.
messages webhook object must be subscribed and functional on the connected Business account. Reviewers test DM delivery, and the endpoint must acknowledge receipt. Apps that only poll the API instead of using webhooks will not pass this permission review.
leadgen event on the Page. Apps that retrieve leads by polling the API alone — without a webhook subscription in place — will not demonstrate a compliant integration during review. See the leads_retrieval approval guide for the full requirements.
comments webhook object. Without an active webhook subscription, the real-time use case for this permission cannot be demonstrated to reviewers in a verifiable way. Full submission requirements are in the instagram_manage_comments approval guide.
feed webhook object active and subscribed on the Page. The permission itself may pass review as a write-access grant, but subscription-based workflows that depend on real-time delivery require a working webhook to demonstrate functional end-to-end use.
How Webhook Setup Works for App Review (Overview)
Register the webhook callback URL in your App Dashboard
Under the Webhooks product in your App Dashboard, you register a publicly accessible HTTPS URL and a verification token. Meta sends a GET request to that URL with hub.mode=subscribe, hub.challenge, and hub.verify_token. Your endpoint must verify the token matches and return the hub.challenge value to complete URL verification. This is the handshake — without it, no webhooks are configured at all.
Subscribe to the specific webhook objects and fields that match your permission
Registering the callback URL is step one only. You must separately subscribe the Page, User, or Instagram Account to the specific webhook objects and fields that correspond to each permission — for example, subscribing to the messages field on a Page for pages_messaging. Missing this subscription step is one of the most common webhook failures: the URL is registered, the endpoint responds, but no events are ever delivered because the subscription does not exist.
Verify the endpoint processes and acknowledges events correctly
When Meta delivers a webhook event via HTTP POST, your endpoint must return an HTTP 200 status within 20 seconds. It must also handle duplicate event delivery (Meta may retry failed deliveries) and must not return 4xx or 5xx responses. Endpoints that acknowledge the challenge correctly but fail on POST event delivery create a scenario where the webhook appears configured but does not actually function — exactly what reviewers will detect during testing.
Test in a Live Mode context before submission
Webhook events in Development Mode are restricted to test users and behave differently from production delivery. Meta's reviewers test permissions in a Live Mode context. If your webhook only processes events correctly in Development Mode — or only from specific test user accounts — the reviewer's test event will not complete successfully, and the permission will not be verifiable. End-to-end testing in Live Mode before submission is the only reliable check.
Why Webhook Setups Fail App Review
For full context on what Meta App Review requires beyond webhooks — including screencast requirements, privacy policy URL standards, and Business Verification gating — see the Facebook App Review support service. If the webhook plumbing is what is holding up your submission, you can get a Facebook API developer to wire it up properly.