PHPackages                             strucura/webhooks - 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. [Utility & Helpers](/categories/utility)
4. /
5. strucura/webhooks

ActiveLibrary[Utility & Helpers](/categories/utility)

strucura/webhooks
=================

Lightweight utilities for dispatching and managing webhooks from your application. This package provides a small Connector abstraction, a WebhookProcessor contract for building outgoing requests, and job wiring that records attempts and schedules retries.

0.4(2mo ago)085[2 PRs](https://github.com/strucura/webhooks/pulls)MITPHPPHP ^8.3CI passing

Since Feb 16Pushed 2mo agoCompare

[ Source](https://github.com/strucura/webhooks)[ Packagist](https://packagist.org/packages/strucura/webhooks)[ Docs](https://github.com/strucura/webhooks)[ GitHub Sponsors](https://github.com/Strucura)[ RSS](/packages/strucura-webhooks/feed)WikiDiscussions 0.x Synced 1mo ago

READMEChangelog (4)Dependencies (13)Versions (6)Used By (0)

Webhooks
========

[](#webhooks)

Caution

This is not ready for production usage, use at your own risk.

[![Latest Version on Packagist](https://camo.githubusercontent.com/57d2ff19f5f6b50d5e214a749729211939ed73525ff372abd5edd12afdaebce6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f73747275637572612f776562686f6f6b732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/strucura/webhooks)[![GitHub Tests Action Status](https://camo.githubusercontent.com/7a42e6197807f1ab8d94c7a2fe4aedcf7f4c503f26287f562a21c058f3fbc808/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f73747275637572612f776562686f6f6b732f72756e2d74657374732e796d6c3f6272616e63683d302e78266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/strucura/webhooks/actions?query=workflow%3Arun-tests+branch%3A0.x)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/400935fd0d6d4465d8ac11d840b72dd2fdbe79cff3f68a8d0036cc92b5e914f1/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f73747275637572612f776562686f6f6b732f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d302e78266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/strucura/webhooks/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3A0.x)[![Total Downloads](https://camo.githubusercontent.com/e18b92b6dbb9610ed94ddfd6c4d66fc0ec5aadcc9806a834c233b171d69d8ba3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f73747275637572612f776562686f6f6b732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/strucura/webhooks)

Lightweight utilities for dispatching and managing webhooks from your application. This package provides a small Connector abstraction, a WebhookProcessor contract for building outgoing requests, and job wiring that records attempts and schedules retries.

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

[](#installation)

You can install the package via composer:

```
composer require strucura/webhooks
```

You can publish and run the migrations with:

```
php artisan vendor:publish --tag="webhooks-migrations"
php artisan vendor:publish --tag="webhooks-config"
php artisan migrate
```

Quick overview
--------------

[](#quick-overview)

- **Connector**: encapsulates base URL, default headers and client options. Optionally implements rate limiting to protect external APIs.
- **WebhookProcessor**: responsible for producing the request data and choosing the Connector to use.
- **ProcessWebhookJob**: invokes the processor, logs results, saves attempts, and schedules retries when appropriate. Automatically handles rate limiting via middleware.

### Configuration Example

[](#configuration-example)

```
use Strucura\Webhooks\BackoffStrategies\ExponentialBackoff;
use App\Webhooks\Events\OrderCreatedEvent;
use App\Webhooks\Processors\OrderCreatedProcessor;

return [
    'defaults' => [
        'max_attempts' => 5,
        'queue' => 'webhooks',
        'backoff_strategy' => new ExponentialBackoff(2, 600),
    ],

    'events' => [
        OrderCreatedEvent::class => [
            'processor' => OrderCreatedProcessor::class,
            'max_attempts' => 10, // Override default
            'backoff_strategy' => new JitteredBackoff(60, 30), // Override default
        ],
    ],
];
```

Backoff Strategies
------------------

[](#backoff-strategies)

Backoff strategies determine the delay between webhook retry attempts. Configure them in your `config/webhooks.php` file.

StrategyDescriptionParametersExample Usage`StaticIntervalBackoff`Fixed delay between all retries`$waitTimeInSeconds` (int)`new StaticIntervalBackoff(60)` - waits 60 seconds between each retry`ExponentialBackoff`Exponentially increasing delay (2^n)`$baseWaitTime` (int, default: 1)
`$maxWaitTime` (int, default: 60)`new ExponentialBackoff(1, 300)` - starts at 1s, doubles each time, caps at 300s`LinearBackoff`Linearly increasing delay`$baseWaitTime` (int, default: 1)`new LinearBackoff(30)` - waits 30s, 60s, 90s, 120s...`JitteredBackoff`Linear delay with random jitter to prevent thundering herd`$baseWaitTime` (int, default: 1)
`$maxJitter` (int, default: 5)`new JitteredBackoff(30, 10)` - waits 30s + 0-10s random, then 60s + 0-10s random...Artisan Commands
----------------

[](#artisan-commands)

The package includes several artisan commands for managing webhooks.

CommandDescriptionOptionsExample`webhooks:retry`Retry failed webhooks that haven't reached max attempts`--all` - Retry all incomplete webhooks regardless of attempt count`php artisan webhooks:retry`
`php artisan webhooks:retry --all``webhooks:increase-attempts`Interactively increase max attempts for a specific webhookNone (interactive prompts)`php artisan webhooks:increase-attempts``make:connector`Generate a new Connector classStandard make command options`php artisan make:connector StripeConnector``make:webhook-processor`Generate a new WebhookProcessor classStandard make command options`php artisan make:webhook-processor StripeChargeProcessor`Rate Limiting
-------------

[](#rate-limiting)

Protect external APIs from being overwhelmed by implementing rate limiting on your connectors. Rate limiting prevents your application from exceeding API rate limits and receiving 429 errors.

### How It Works

[](#how-it-works)

- **Job Middleware**: Rate limiting is implemented via job middleware that checks before webhook execution
- **Automatic Retry**: When rate limited, jobs are released back to the queue with an appropriate delay
- **Doesn't Consume Attempts**: Throttled jobs don't count toward max retry attempts
- **Per-Connector Configuration**: Each connector can define its own rate limits

### Basic Usage

[](#basic-usage)

Implement the `HasRateLimit` contract on any connector to enable rate limiting:

```