> ## 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.

# Lead ad debugging for Facebook

> Debug Facebook lead ad issues in the HoopAI platform, including leads not syncing, webhook failures, field mapping problems, and testing with the Facebook Lead Ads Testing Tool.

When Facebook lead ads are not delivering leads into the HoopAI platform as expected, the issue typically falls into one of a few categories: webhook delivery failures, field mapping mismatches, or permission problems. This guide walks you through a systematic debugging process.

<Note>
  Before debugging, confirm that your Facebook Lead Ads integration is connected in **Settings > Integrations > Facebook**. If the integration is not connected at all, see [Troubleshooting Facebook Lead Ads integration](/troubleshooting/facebook-lead-ads-integration).
</Note>

***

## Leads not coming in

If new form submissions on Facebook are not creating contacts or triggering workflows in Hoop, follow these steps:

<Steps>
  <Step title="Check the integration status">
    Go to **Settings > Integrations > Facebook** and verify the connection shows as active. A red or warning status indicates the integration needs to be re-authenticated.
  </Step>

  <Step title="Verify the correct Facebook page is selected">
    Ensure the Facebook page associated with your lead ad is selected in the integration settings. If you manage multiple pages, leads will only sync from pages that are explicitly connected.
  </Step>

  <Step title="Confirm form selection">
    In the integration settings, verify that the specific lead form is mapped. Hoop does not automatically import leads from all forms — each form must be individually selected.
  </Step>

  <Step title="Review the lead ad status in Facebook">
    Open **Facebook Ads Manager** and confirm the ad is active and has received submissions. If the ad has no leads, the issue is on the Facebook side, not in Hoop.
  </Step>
</Steps>

***

## Webhook failures

Hoop receives leads from Facebook via webhooks. If webhooks are failing:

| Symptom                                  | Likely cause                      | Resolution                                                          |
| ---------------------------------------- | --------------------------------- | ------------------------------------------------------------------- |
| Leads appear in Facebook but not in Hoop | Webhook endpoint unreachable      | Re-authenticate the integration to refresh the webhook subscription |
| Intermittent lead delivery               | Rate limiting or transient errors | Check **Settings > Integrations > Facebook > Logs** for error codes |
| Duplicate leads appearing                | Webhook retries after timeout     | Enable duplicate detection in your workflow or contact Hoop support |

<Warning>
  Facebook retries failed webhook deliveries for up to 24 hours. If your integration was temporarily disconnected, you may see a batch of delayed leads arrive at once after reconnecting.
</Warning>

***

## Field mapping problems

If leads are arriving but with missing or incorrect data:

<AccordionGroup>
  <Accordion title="Custom fields not mapping">
    Facebook custom questions require manual field mapping in Hoop. Go to **Settings > Integrations > Facebook**, select the form, and map each custom question to the corresponding Hoop contact field.
  </Accordion>

  <Accordion title="Phone number or email missing">
    Facebook pre-fills these fields from the user's profile, but users can clear them before submitting. Check the raw lead data in Facebook Ads Manager to confirm whether the field was submitted.
  </Accordion>

  <Accordion title="Data appearing in the wrong field">
    Review the field mapping order. If Facebook form fields were reordered after the initial mapping, the field assignments in Hoop may no longer match. Re-map the fields to correct this.
  </Accordion>
</AccordionGroup>

***

## Testing with the Facebook Lead Ads Testing Tool

Facebook provides a built-in testing tool that sends a test lead to your webhook without requiring a live ad.

<Steps>
  <Step title="Open the testing tool">
    Go to [Facebook Lead Ads Testing Tool](https://developers.facebook.com/tools/lead-ads-testing) and sign in with the Facebook account that owns the page.
  </Step>

  <Step title="Select your page and form">
    Choose the Facebook page and the lead form you want to test from the dropdown menus.
  </Step>

  <Step title="Create a test lead">
    Click **Create Lead**. Facebook sends a test submission through the same webhook that handles real leads.
  </Step>

  <Step title="Verify in Hoop">
    Check **Contacts** in Hoop for a new contact with test data. If the test lead does not appear, the webhook configuration is the issue — re-authenticate the integration.
  </Step>
</Steps>

<Tip>
  Test leads created through the Facebook testing tool are marked with test data. Delete these test contacts from Hoop after debugging to keep your contact list clean.
</Tip>

***

## Permission requirements

Facebook lead ad integrations require specific permissions to function:

* **pages\_manage\_ads** — allows Hoop to read lead form configurations
* **leads\_retrieval** — allows Hoop to receive and download lead data
* **pages\_show\_list** — allows Hoop to list your connected pages

If any of these permissions were revoked or were not granted during setup, the integration will fail silently. Re-authenticate the integration in **Settings > Integrations > Facebook** to re-grant all required permissions.

<Info>
  If you are a page admin but not the business account owner, you may need the business account owner to approve the integration permissions in Facebook Business Settings.
</Info>