A package to retrieve Facebook Leads with webhooks & Graph API in Laravel.

v1.0.3 2021-05-06 08:25 UTC

This package is auto-updated.

Last update: 2021-05-06 08:26:02 UTC


Latest Version on Packagist GitHub Tests Action Status GitHub Code Style Action Status Total Downloads


You can install the package via composer:

composer require marshmallow/laravel-facebook-webhook

This package uses spatie/laravel-webhook-client & Laravel Socialite Please read the instructions from both packages!

Publish the migrations from spatie/laravel-webhook-client To create the table that holds the webhook calls, you must publish the migration with:

php artisan vendor:publish --provider="Spatie\WebhookClient\WebhookClientServiceProvider" --tag="migrations"

Make sure to add the correct config for the Spatie Webhook Package:

'name' => 'facebook-lead',
'signing_secret' => env('FACEBOOK_CLIENT_SECRET'),
'signature_header_name' => 'X-Hub-Signature',
'signature_validator' => \Marshmallow\LaravelFacebookWebhook\SignatureValidator\FacebookSignatureValidator::class,
'process_webhook_job' => \Marshmallow\LaravelFacebookWebhook\Jobs\ProcessFacebookLeadWebhookJob::class,

Please see the Base Installation Guide, then follow the provider specific instructions below.

Add configuration to config/services.php

'facebook' => [
  'client_id' => env('FACEBOOK_CLIENT_ID'),
  'client_secret' => env('FACEBOOK_CLIENT_SECRET'),
  'redirect' => env('FACEBOOK_REDIRECT_URI')

You can publish the config & migration files with:

php artisan vendor:publish --provider="Marshmallow\LaravelFacebookWebhook\LaravelFacebookWebhookServiceProvider"

After the migration has been published, you can create the webhook_calls table by running the migrations:

php artisan migrate

Make sure to have the following .env variables setup:

FACEBOOK_CALLBACK_ROUTE= #Default set 'webhook-client-facebook-lead'
FACEBOOK_REDIRECT_URI= #'/auth/facebook'


This is the contents of the file that will be published at config/facebook-webhook.php:

        'configs' => [
             * This package supports multiple webhook receiving endpoints. If you only have
             * one endpoint receiving webhooks, you can use 'default'.
            'name' => 'facebook-lead',

             * The class name of the job that will process the Facebook Lead Data.
             * This should be set to a class that extends \Marshmallow\LaravelFacebookWebhook\Jobs\ProcessFacebookLeadJob,
            'process_facebook_webhook_job' => '',

             * The callback route name from Facebook Leads .
            'callback_route' => env('FACEBOOK_CALLBACK_ROUTE', 'webhook-client-facebook-lead'),

             * The graph api version for Facebook  .
            'graph_api_version' => 'v10.0',

             * The App ID from the Facebook App.
            'app_id' => env('FACEBOOK_CLIENT_ID'),

             * The App Secret from the Facebook App.
            'app_secret' => env('FACEBOOK_CLIENT_SECRET'),

             * The Page ID to retrieve the leads from.
            'page_id' => env('FACEBOOK_PAGE_ID'),


Create an Facebook app using the following instructions from Facebook, make sure your app has the following permissions: A Page or User access token requested by a person who can advertise on the ad account and on the Page

  • The ads_management permission
  • The leads_retrieval permission
  • The pages_show_list permission
  • The pages_read_engagement permission
  • The pages_manage_ads permission

After setting up the migrations and the .env, run:

php artisan marshmallow:setup-facebook


This package uses spatie/laravel-webhook-client to retrieve and process the incoming Facebook Webhook. For initial Facebook authentication it uses Laravel Socialite. On an incoming webhook, it retrieves the Lead data through the Facebook Graph API and sends an event on completion. You can specify which job should process the Lead data in the process_facebook_webhook_job in the facebook-webhook config file.

For example make a Job:

    use Marshmallow\LaravelFacebookWebhook\Jobs\ProcessFacebookLeadJob as MarshmallowWebhookJob;

    class ProcessFacebookDataJob extends MarshmallowWebhookJob
         * Execute the job.
         * @return void
        public function handle()

And add it to the config:

    'process_facebook_webhook_job' => \App\Jobs\ProcessFacebookDataJob::class,


Please see CHANGELOG for more information on what has changed recently.


Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.



The MIT License (MIT). Please see License File for more information.