Nova Webhooks Laravel Package

Getting Started

• Treat v2.0.0 as a Nova 5 compatibility major, not a feature release. The release notes only list dependency updates for Nova 5, so the first job is to verify your app’s Nova/Laravel/PHP constraints before upgrading.
• Start with:
  • composer.json diff in PR #18 and the package’s composer.json constraints.
  • The README’s install/configuration section.
  • The published config file, migrations, and Nova tool/card registration instructions.
• Typical install path:

composer require dniccum/nova-webhooks:^2.0
php artisan vendor:publish --provider="Dniccum\\NovaWebhooks\\NovaWebhooksServiceProvider"
php artisan migrate

Register the package’s Nova tool/card in app/Providers/NovaServiceProvider.php per the README (tools() or cards() — confirm against the package docs for your Nova version).

• First practical use case: configure one webhook endpoint for a low-risk Nova resource event, send a test payload, and verify the request arrives with the expected payload and headers. Use a request-bin service or a local tunnel before wiring production endpoints.

Implementation Patterns

• Pin to the Nova major you run. Use ^2.0 on Nova 5. If you are still on Nova 4 or earlier, stay on the v1.x line unless you have explicitly tested the upgrade.
• Upgrade in a branch. Bump the package, run composer update dniccum/nova-webhooks --with-dependencies, clear config cache, run migrations, then exercise the Nova UI and webhook delivery flow.
• Keep webhook delivery asynchronous. If the package supports queued delivery, use it for non-critical webhooks so Nova admin requests are not blocked by slow external endpoints. Run queue workers in every environment where webhooks should fire.
• Separate environments. Use different webhook endpoints/secrets for local, staging, and production. In local development, expect to need a tunnel such as ngrok or a local request catcher.
• Make consumers idempotent. Include or derive a stable event/resource identifier in the payload where possible, and let receivers deduplicate retries.
• Test outgoing HTTP with Laravel fakes. For application-level integration tests, use Http::fake() around the code paths that trigger webhooks. For Nova UI/tool registration, add a simple feature test that boots Nova and confirms the tool/card appears.
• Wrap package-specific behaviour behind your own service/action if you need custom payload shaping, event filtering, or delivery rules. That keeps upgrade friction low if the package’s internals change between Nova majors.
• Use it for Nova-driven notifications, not as a full webhook platform. Common day-to-day uses: notify an external system when a Nova-managed record is created/updated, send operational events to Slack/automation endpoints, or sync selected Nova actions with another service.

Gotchas and Tips

• v2.0.0 is a major version for a reason. Even though the release notes only mention dependency compatibility, assume Nova 4 support may be dropped. Check composer why-not dniccum/nova-webhooks 2.0.0 if the upgrade resolves unexpectedly.
• Release notes are thin. Diff v1.1.3...v2.0.0 and inspect composer.json, service providers, config, and migrations before upgrading production. Do not assume there are no internal API changes just because only dependencies are listed.
• Config cache bites. After publishing config or changing webhook settings, run php artisan config:clear locally and php artisan config:cache as part of deployment.
• Queue failures are the usual silent failure mode. Check failed_jobs, worker logs, and the package’s own logs if webhooks stop arriving. A successful Nova save does not guarantee a successful webhook delivery.
• Protect secrets and verify inbound requests at the receiver if the package supports signing/secrets. Rotate secrets with an overlap window, and never commit production webhook secrets.
• Local development needs a public endpoint. If webhooks do not arrive locally, first confirm the endpoint is reachable from the outside, then check the package config and queue worker.
• Debug registration with Laravel/Nova tooling. Use php artisan route:list to look for package routes, check storage/logs/laravel.log, and confirm the tool/card is registered in NovaServiceProvider.
• Extension points to look for: configurable endpoints, event/resource filtering, queue connection, payload transformation, signing secret, and retry/backoff settings. If the package does not expose what you need, prefer wrapping it over patching vendor files.