Download the PHP package meilleursbiens/laravel-proabono-webhook without Composer

Receive ProAbono webhooks in Laravel

ProAbono notifies your application of every billing event — a subscription starting, an invoice being paid, a card about to expire — by POSTing a webhook to a URL you own.

This package wires those notifications into a Laravel app. It is a thin, opinionated layer on top of spatie/laravel-webhook-client that adds what is specific to ProAbono:

• the signature validator matching ProAbono's scheme (which is not an HMAC of the body);
• the activation handshake, captured and surfaced through an Artisan command;
• the 44 documented triggers as a PHP enum;
• a typed payload reader over the real notification body — customer, subscription, offer, invoice, payment method;
• events and per-trigger jobs so your code never parses a raw payload.

Requirements

PHP 8.2+ and Laravel 12 or 13.

Laravel 11 is not supported: every 11.x release is affected by security advisories that were only ever fixed in 12.60+, so Composer's default policy refuses to install it at all.

Installation

Publish the config file and the webhook_calls migration, then migrate:

Add your ProAbono secret key to .env:

You will find it in the ProAbono back office, under Integration. It is the same secret used to sign API calls — treat it as a credential.

That is all: the package registers POST /proabono/webhook for you. Change the path with PROABONO_WEBHOOK_URL, or set proabono-webhook.route.enabled to false and declare it yourself:

The route is registered outside the web middleware group, so it has no session and no CSRF verification — nothing to exclude, unlike a hand-rolled endpoint.

Webhook payloads are processed in a queued job. Use a real queue driver rather than sync, so ProAbono gets its 200 OK immediately.

Activating the webhook in ProAbono

ProAbono will not send you anything until the endpoint has been validated.

1. In the back office, go to Integration → My webhooks → New webhook.
2. Set the notification URL to https://your-app.test/proabono/webhook and tick the events you care about.
3. Click Send verification code. ProAbono POSTs a one-time code to your URL.

4. Read the code back:

5. Paste it into the back office. The webhook flips to Active.

The handshake is stored like any other call and is always accepted, even when you filter triggers — so you can never lock yourself out of activation. If you would rather forward the code somewhere (Slack, mail, a log), listen for ProAbonoVerificationCodeReceived:

For local development, expose your machine with php artisan serve behind Expose or ngrok, and point the webhook at the public URL.

How the signature is verified

ProAbono does not sign the request body. Each call carries two headers:

Knowing the digest proves the sender knows your secret. ProAbonoSignatureValidator recomputes it and compares in constant time; a call that fails is answered with a 500, never stored, and fires spatie's InvalidWebhookSignatureEvent.

Because the signature does not cover the body, it authenticates the sender, not the payload. Always serve the endpoint over HTTPS.

While replaying captured payloads locally you can switch the check off — never in production:

Reacting to events

Per-trigger jobs

Map a trigger to a job in config/proabono-webhook.php. The job receives the stored ProAbonoWebhookCall as its only constructor argument:

Keys are matched case-insensitively, so subscription_started and SubscriptionStarted both work.

Events

Every notification also fires two events.

A string event named after the trigger, receiving the webhook call:

And a class event for a single entry point:

Filtering what you store

By default every notification is stored. Narrow it down when you only care about a few triggers — anything else is answered 200 OK and dropped:

Reading a payload

ProAbonoWebhookCall::notification() returns a ProAbonoNotification: a read-only, typed view over the JSON body.

Every notification shares the same envelope and always carries a Customer:

Beyond that, each trigger carries the sub-objects its category implies:

Shortcuts for the ids you match on most often:

Anything not modelled stays reachable, and the untouched body is always kept in payload:

A missing or unexpected value yields null rather than an exception, so a payload change never breaks a queue worker mid-flight. An unknown trigger is not an error either: trigger() returns null while triggerName() still gives you the raw string, so a newly introduced ProAbono event is stored rather than dropped. Set throw_on_unrecognized_payload to true to have such payloads surface through your error tracker instead.

Amounts are integers in the smallest currency unit — 4491 means 44.91. The currency itself is not part of the notification; read it from your offer or from the ProAbono API.

A worked example

Getting a sample for any trigger

The ProAbono back office serves a sample body for each trigger, which is where the fixtures in tests/fixtures/samples/ come from:

It answers {"TypeTrigger": "…", "Data": "<the body, JSON encoded>"}. ProAbonoNotification unwraps that envelope on its own, so you can POST a sample straight to your endpoint without unpacking it first.

Querying stored calls

Prune old rows by scheduling model:prune in routes/console.php:

The window comes from proabono-webhook.delete_after_days (30 by default).

Retries and idempotency

ProAbono keeps re-sending a notification until it gets a response in the 200 range. This package answers 200 as soon as the call is stored, so a retry means your app was genuinely unreachable — but a retry can still arrive after your job has already run. Make your handlers idempotent (guard on IdSubscription / IdInvoice plus the trigger, or on the state you are about to write).

Supported triggers

The ProAbonoTrigger enum covers all 44 documented events.

Testing your integration

ProAbonoSignatureValidator::sign() forges a valid signature, so you can hit your own endpoint from a test:

The package ships the back office's sample body for all 44 triggers in tests/fixtures/samples/, and replays each of them through the endpoint in its own suite. Run it with:

Reference

• ProAbono — Webhooks
• ProAbono — How to secure a webhook
• ProAbono — How to validate a webhook
• ProAbono — List of events notified by the webhooks
• spatie/laravel-webhook-client

License

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