Laravel Webhook Console Laravel Package

Getting Started

Install the package and publish its config and migrations, then run php artisan migrate. Set the webhook signing secret(s) in config/webhooks.php (or via env) before exposing the receiving endpoint — unsigned or mis-signed requests are rejected before they ever reach your handlers, which is the correct default but also the most common first-day "nothing is arriving" cause.

The first thing to open is the dashboard. Send a test payload with curl (or your provider's "send test event" button), confirm the call appears, then deliberately break your handler (throw in the job) and use the dashboard's replay action on the failed record. That single loop — receive → inspect payload → replay — is the package's core value and validates your whole setup: route, signature config, queue, and job dispatch.

If you prefer the CLI, php artisan webhooks:replay is the same operation without the UI. Start there when you are debugging on a remote/staging box where the dashboard is not exposed.

Implementation Patterns

Receive thin, dispatch immediately. Keep the HTTP entry point trivial: verify, persist the WebhookCall, dispatch a job, return 200 fast. Providers retry aggressively on slow responses, and you do not want your business logic inside the request cycle. The persisted record is what makes replay possible later, so do not disable storage to "save a table".

Treat replay as the primary recovery tool, not a rare escape hatch. Wire your failed jobs to alert (Slack/email) with a link to the dashboard filtered to failures. The day-to-day workflow becomes: alert fires → open dashboard → inspect stored payload → fix the bug → deploy → replay the affected calls → confirm they turn green. Because the payload is stored verbatim, replays work even after the provider has stopped retrying.

Schedule pruning from day one. Webhook payloads are bulky and grow fast. Add $schedule->command('webhooks:prune')->daily(); in routes/console.php (or your scheduler) and set the retention window in config to match your compliance posture. Decide up front whether you keep successes, failures only, or everything — retaining failures is usually the useful compromise.

Use payload search as a debugging tool, not a monitoring metric. Searching the raw payload is the fastest way to answer "did we ever receive event X for customer Y?" and to find a specific call to replay. Build your own indexed columns (event type, external id) on top if you need dashboards or counts — do not scrape the search UI's notices for numbers.

Make handlers idempotent. Replay means the same payload can hit your handler more than once, and providers retry independently of your replay. Key your side effects on the webhook call id or the provider's event id, and guard writes accordingly.

Isolate environments. Use separate signing secrets and, ideally, separate tables/databases per environment. Replaying a production payload into a staging handler is a legitimate and very useful workflow — replaying it into production twice is not.

Test against the stored model, not the HTTP layer. For handler tests, construct a webhook call record from a fixture payload and run the job directly; keep a small number of feature tests that hit the route to prove signature verification still works.

Gotchas and Tips

Exception details are deliberately hidden (v1.0.2). The dashboard flash message after a failed replay and the webhooks:replay CLI output now mask the exception class and message, the same as other exception text in the package. This is a security improvement, but it changes your debugging loop: the replay output tells you that it failed, not why. Go to your application logs (or the failed-jobs table) for the real exception; make sure your log channel is actually capturing job failures before you rely on replay during an incident. Do not build tooling that parses the replay message for the exception class — it is now intentionally useless for that.

Payload search no longer reports raw match counts (v1.0.2). The "only the newest matches were checked" notice carries no number, and it only appears when the search also returned something visible. Two consequences: an empty result with no notice means "nothing visible matched" rather than "nothing matched at all", and you can no longer use the notice to probe whether a guessed value exists in the payload table. If you had a support runbook that asked ops to read the match count out of the notice, update it — and be aware that the UI is now intentionally less informative when you are searching for a secret-looking string. Search for the surrounding context (external id, event name) instead of the secret itself.

Prune messaging is now grammatically correct (v1.0.2). webhooks:prune and the dashboard's prune confirmation say "1 day" instead of "1 days". Cosmetic only, but if you have log-parsing or alerting on prune output, the string changed — match on the command rather than the human-readable text.

Signature config is the usual culprit. A 403 with no stored record almost always means the secret, the signature header name, or a signing algorithm mismatch — not a package bug. Check the provider's signing version (many send both a v1 and a v2 signature) and confirm you are comparing against the raw body, not a re-encoded copy.

Replay respects the queue. If replay appears to do nothing, check that a worker is running for the configured connection/queue. A replay that "succeeds" instantly with no side effects usually means it was queued, not executed.

Failures during replay are recorded, not thrown at you. Catch and surface them at the dashboard/log level; do not wrap the replay call in a try/catch expecting an exception to propagate.

Watch payload size. Some providers send multi-megabyte payloads. Long-text columns and generous retention will bloat the table; prune more aggressively for high-volume endpoints, and consider trimming payloads you will never need to replay if storage becomes a problem.

Extension point: the failure/replay flow is best customised at the job level — subclass or wrap the dispatched job to add metrics, tracing, or per-event routing — rather than by forking the dashboard. Keep package views unpublished unless you genuinely need to change them; they are the part most likely to change between releases.