Download the PHP package hotmeteor/receiver without Composer

Receiver

Receiver is a drop-in webhook handling library for Laravel.

Receiver gives you a consistent, expressive way to receive, verify, and handle incoming webhooks in your Laravel app. Point a route at a controller, call three methods, and you're done.

Out of the box, Receiver supports:

Any other webhook source can be added with a custom provider.

Table of Contents

• Installation
• Configuration
• Receiving Webhooks
  • Single provider
  • Multiple providers
  • Fallbacks
• Handling Webhooks
  • Handler naming
  • Queueing handlers
• Extending Receiver
  • Generating a provider
  • Defining getEvent() and getData()
  • Securing webhooks
  • Handshakes
  • Multiple events per request
  • Creating a community provider
• Share Your Receivers!
• Credits
• License

Installation

Requires PHP ^8.2 and Laravel 10+.

Note: The Stripe provider requires stripe/stripe-php:

Configuration

Each provider reads its secret from config/services.php. Add an entry for each source you intend to receive from.

Most providers use the same shape:

Mailchimp — Mailchimp Marketing webhooks are verified via a secret you embed in your webhook URL (?secret=...). Configure the same value here so Receiver can compare it:

SendGrid — Signature verification is opt-in. Set webhook_secret to the PEM-format public key found in the SendGrid dashboard under Settings → Mail Settings → Event Webhook. Leave it empty to accept all requests without verification.

Postmark — Postmark supports several verification strategies. Configure which ones to use under the webhook key:

If verification_types is empty or not set, all Postmark requests are accepted without verification.

Receiving Webhooks

Single provider

Create a controller and route for each webhook source, then call driver(), receive(), and ok():

• driver() — selects the provider and reads its config
• receive() — verifies the signature and maps the event
• ok() — dispatches matched handlers and returns a 200 response

Multiple providers

If you'd rather handle all webhooks through a single controller, use a {provider} route parameter:

Or use the included ReceivesWebhooks trait, which provides this exact store() method for you:

Fallbacks

Receiver silently ignores events it has no handler for. If you'd like to do something with unhandled events, add a fallback() callback before ok():

Handling Webhooks

Once a webhook is received, Receiver looks for a handler class that matches the event and dispatches it. Handlers live in App\Http\Handlers\{Driver}\ by default. If no matching handler is found the webhook is silently ignored and a 200 is returned.

Handler naming

The handler class name is derived from the event name — all non-alphanumeric characters are treated as word separators, then converted to StudlyCase:

For example, Stripe's customer.created event dispatches App\Http\Handlers\Stripe\CustomerCreated.

Each handler receives the $event name and the $data array, and must use the Dispatchable trait:

Queueing handlers

Because Receiver calls dispatch() on each handler, making a handler queued is as simple as implementing ShouldQueue:

See the Laravel queue documentation for full details.

Extending Receiver

A provider is a PHP class that tells Receiver how to extract the event name, the payload data, and optionally how to verify the request's authenticity.

Generating a provider

The quickest way to scaffold a new provider is with the receiver:make Artisan command:

The generated class is placed in App\Http\Receivers. Once created, register the driver in your AppServiceProvider:

Defining getEvent() and getData()

Implement getEvent() to return the event name. Optionally implement getData() to return the event payload — by default it returns $request->all().

Securing webhooks

Implement a verify() method that returns true if the request is authentic, or false to reject it with a 401 response:

The signing secret from config/services.{driver}.webhook_secret is available as $this->secret.

Handshakes

Some services send a verification request when a webhook URL is first registered. Implement handshake() to respond to it:

When handshake() returns a non-empty array, Receiver responds immediately with that payload and skips normal event handling. When it returns an empty array, Receiver processes the request normally.

Multiple events per request

Some services batch multiple events into a single request. Return an ['event_name' => $eventData] array from getEvent() and Receiver will dispatch a separate handler for each entry:

Creating a community provider

If you're building a reusable provider package to share, add the --provider flag to also generate a companion ServiceProvider that registers the driver automatically:

This generates:

• app/Http/Receivers/MailgunProvider.php — your provider class
• app/Providers/MailgunReceiverServiceProvider.php — auto-registers the driver via Receiver::extend()

To support Laravel package auto-discovery, add the service provider to your package's composer.json:

Users who install your package will have the driver available immediately, with no manual registration required.

Share Your Receivers!

Built a provider for a service not listed above? Share it with the community in the Receivers Discussion topic!

Credits

• Adam Campbell
• All Contributors

Made with contributors-img.

License

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