PHPackages                             hotmeteor/receiver - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. hotmeteor/receiver

ActiveLibrary[API Development](/categories/api)

hotmeteor/receiver
==================

A drop-in webhook handling library for Laravel

v1.0.0(2mo ago)393154.2k↓24.2%23MITPHPPHP ^8.2CI passing

Since Aug 22Pushed 2mo ago2 watchersCompare

[ Source](https://github.com/hotmeteor/receiver)[ Packagist](https://packagist.org/packages/hotmeteor/receiver)[ GitHub Sponsors](https://github.com/hotmeteor)[ Fund](https://ko-fi.com/hotmeteor)[ RSS](/packages/hotmeteor-receiver/feed)WikiDiscussions main Synced 3d ago

READMEChangelog (10)Dependencies (12)Versions (26)Used By (0)

[![Receiver](./art/logo.png)](./art/logo.png)

Receiver
========

[](#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:

ProviderDriver[GitHub](https://docs.github.com/en/developers/webhooks-and-events/webhooks/about-webhooks)`github`[HubSpot](https://developers.hubspot.com/docs/api/webhooks)`hubspot`[Mailchimp Marketing](https://mailchimp.com/developer/marketing/guides/sync-audience-data-webhooks/)`mailchimp`[Paddle Billing](https://developer.paddle.com/webhooks/overview)`paddle`[Postmark](https://postmarkapp.com/developer/webhooks/webhooks-overview)`postmark`[SendGrid Events](https://docs.sendgrid.com/for-developers/tracking-events/getting-started-event-webhook-security-features)`sendgrid`[Shopify](https://shopify.dev/docs/apps/webhooks)`shopify`[Slack Events API](https://api.slack.com/apis/connections/events-api)`slack`[Stripe](https://stripe.com/docs/webhooks)`stripe`[Twilio](https://www.twilio.com/docs/usage/webhooks)`twilio`Any other webhook source can be added with a [custom provider](#extending-receiver).

[![Tests](https://github.com/hotmeteor/receiver/workflows/Tests/badge.svg)](https://github.com/hotmeteor/receiver/workflows/Tests/badge.svg)[![Latest Version on Packagist](https://camo.githubusercontent.com/db5e67060b17b5a399362ab91d6edd8404881786a9406495e9a72c1c61a825ed/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f767072652f686f746d6574656f722f72656365697665722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/hotmeteor/receiver)[![PHP from Packagist](https://camo.githubusercontent.com/80600d8474e21866c0167e8ce17537529e0833534570acbbf4c343f90fb9538a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f686f746d6574656f722f7265636569766572)](https://camo.githubusercontent.com/80600d8474e21866c0167e8ce17537529e0833534570acbbf4c343f90fb9538a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f686f746d6574656f722f7265636569766572)

Table of Contents
-----------------

[](#table-of-contents)

- [Installation](#installation)
- [Configuration](#configuration)
- [Receiving Webhooks](#receiving-webhooks)
    - [Single provider](#single-provider)
    - [Multiple providers](#multiple-providers)
    - [Fallbacks](#fallbacks)
- [Handling Webhooks](#handling-webhooks)
    - [Handler naming](#handler-naming)
    - [Queueing handlers](#queueing-handlers)
- [Extending Receiver](#extending-receiver)
    - [Generating a provider](#generating-a-provider)
    - [Defining getEvent() and getData()](#defining-getevent-and-getdata)
    - [Securing webhooks](#securing-webhooks)
    - [Handshakes](#handshakes)
    - [Multiple events per request](#multiple-events-per-request)
    - [Creating a community provider](#creating-a-community-provider)
- [Share Your Receivers!](#share-your-receivers)
- [Credits](#credits)
- [License](#license)

Installation
------------

[](#installation)

Requires PHP ^8.2 and Laravel 10+.

```
composer require hotmeteor/receiver
```

> **Note:** The Stripe provider requires [`stripe/stripe-php`](https://github.com/stripe/stripe-php):
>
> ```
> composer require stripe/stripe-php
> ```

Configuration
-------------

[](#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:

```
'github'   => ['webhook_secret' => env('GITHUB_WEBHOOK_SECRET')],
'hubspot'  => ['webhook_secret' => env('HUBSPOT_WEBHOOK_SECRET')],
'paddle'   => ['webhook_secret' => env('PADDLE_WEBHOOK_SECRET')],
'shopify'  => ['webhook_secret' => env('SHOPIFY_WEBHOOK_SECRET')],
'slack'    => ['webhook_secret' => env('SLACK_WEBHOOK_SECRET')],
'stripe'   => ['webhook_secret' => env('STRIPE_WEBHOOK_SECRET')],
'twilio'   => ['webhook_secret' => env('TWILIO_AUTH_TOKEN')],
```

**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:

```
'mailchimp' => ['webhook_secret' => env('MAILCHIMP_WEBHOOK_SECRET')],
```

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

```
'sendgrid' => ['webhook_secret' => env('SENDGRID_WEBHOOK_PUBLIC_KEY', '')],
```

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

```
'postmark' => [
    'token' => env('POSTMARK_TOKEN'),
    'webhook' => [
        // One or more of: 'auth', 'headers', 'ips'
        'verification_types' => ['headers', 'ips'],

        // Header name => expected value pairs (used with 'headers')
        'headers' => [
            'X-Custom-Header' => env('POSTMARK_WEBHOOK_HEADER'),
        ],

        // Allowed source IPs (used with 'ips')
        // https://postmarkapp.com/support/article/800-ips-for-firewalls#webhooks
        'ips' => [
            '3.134.147.250',
            '50.31.156.6',
            '50.31.156.77',
            '18.217.206.57',
        ],
    ],
],
```

Postmark `verification_type`Description`auth`HTTP Basic Auth via `Auth::onceBasic()``headers`Validates that specific request headers match expected values`ips`Validates that the request originates from an allowed IPIf `verification_types` is empty or not set, all Postmark requests are accepted without verification.

Receiving Webhooks
------------------

[](#receiving-webhooks)

### Single provider

[](#single-provider)

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

```