> ## Documentation Index
> Fetch the complete documentation index at: https://help.hoopai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Facebook Lead Ads integration

> Resolve issues connecting Facebook Lead Ads to the HoopAI platform, including authorization problems, page permissions, lead sync delays, and webhook configuration.

Connecting Facebook Lead Ads to the HoopAI platform allows you to automatically sync leads from your Facebook forms into Hoop contacts and workflows. If the integration is not connecting or leads are not syncing, this guide helps you resolve the most common issues.

<Note>
  You need admin access to both the Facebook page running lead ads and the Hoop account to set up and troubleshoot this integration.
</Note>

***

## Authorization flow issues

If the integration fails during the initial connection:

<Steps>
  <Step title="Ensure pop-ups are enabled">
    The Facebook authorization flow opens in a pop-up window. If your browser blocks pop-ups, the authorization will fail silently. Allow pop-ups for your Hoop domain and try again.
  </Step>

  <Step title="Sign in to the correct Facebook account">
    The pop-up may default to a personal Facebook account that does not have admin access to the page. Sign out of Facebook first, then re-initiate the connection from Hoop and sign in with the correct account.
  </Step>

  <Step title="Grant all requested permissions">
    During authorization, Facebook displays a list of permissions. You must approve all of them. If you deselect any permission, the integration will not function correctly. Re-authorize and grant all permissions.
  </Step>
</Steps>

<Warning>
  If you click **Cancel** during the Facebook authorization flow, the integration will remain in a disconnected state. You must start the connection process again from **Settings > Integrations > Facebook** in Hoop.
</Warning>

***

## Page permissions

The Facebook account used to authorize the integration must have the correct role on the page:

| Role           | Can connect lead ads? |
| -------------- | --------------------- |
| Page Admin     | Yes                   |
| Page Editor    | Yes                   |
| Page Moderator | No                    |
| Page Analyst   | No                    |

If you have the correct role but the page still does not appear in the integration setup, check **Facebook Business Settings > Pages** to confirm the page is assigned to the business account linked to your login.

***

## Form selection and configuration

After connecting the integration, you must select which lead forms to sync:

<AccordionGroup>
  <Accordion title="No forms appear in the dropdown">
    Hoop only displays forms that are published and associated with the selected page. If you recently created a form, it may take a few minutes to appear. Refresh the page and try again.
  </Accordion>

  <Accordion title="Form appears but leads do not sync">
    Verify the form is actively being used in a running ad campaign. Forms that exist but have no associated active ads will not generate leads. Also confirm the form is mapped in the Hoop integration settings.
  </Accordion>

  <Accordion title="Multiple forms showing duplicate names">
    Facebook allows forms with identical names. Use the form ID (displayed in parentheses in the dropdown) to identify the correct form. Cross-reference the ID in Facebook Ads Manager under **Instant Forms**.
  </Accordion>
</AccordionGroup>

***

## Lead sync delays

Under normal conditions, leads arrive in Hoop within 1-2 minutes of form submission. If you experience delays:

1. Check the **Facebook Platform Status** page for any ongoing incidents affecting the Marketing API
2. Review **Settings > Integrations > Facebook > Logs** in Hoop for queued or failed webhook deliveries
3. If delays persist beyond 15 minutes, disconnect and reconnect the integration to reset the webhook subscription

<Info>
  During high-traffic ad campaigns, Facebook may batch webhook deliveries rather than sending them individually. This can add a delay of up to 5 minutes, which is normal behavior.
</Info>

***

## Re-authentication after token expiry

Facebook access tokens used by the integration expire after approximately 60 days. When a token expires:

* New leads will stop syncing to Hoop
* The integration status in **Settings > Integrations > Facebook** changes to a warning or error state
* Existing leads and contacts already in Hoop are not affected

<Steps>
  <Step title="Navigate to the integration settings">
    Go to **Settings > Integrations > Facebook** in Hoop.
  </Step>

  <Step title="Click reconnect">
    Click **Reconnect** or **Re-authenticate**. This opens the Facebook authorization pop-up.
  </Step>

  <Step title="Complete the authorization">
    Sign in to Facebook, grant all requested permissions, and complete the flow. The token is renewed and lead syncing resumes immediately.
  </Step>
</Steps>

<Tip>
  Set a recurring calendar reminder for every 50 days to re-authenticate the integration proactively. This prevents gaps in lead delivery.
</Tip>

***

## Webhook configuration

If leads are still not arriving after verifying all of the above, the webhook subscription may be corrupted:

1. Disconnect the Facebook integration entirely in **Settings > Integrations > Facebook**
2. Wait 30 seconds, then reconnect using the authorization flow
3. Re-select your page and forms
4. Submit a test lead using the [Facebook Lead Ads Testing Tool](https://developers.facebook.com/tools/lead-ads-testing) to confirm delivery

If the test lead arrives in Hoop, the webhook is functioning. If it does not, contact Hoop support with your Facebook page ID and form ID for further investigation.