Nova Zadarma Laravel Package

Getting Started

Nova Zadarma is a Laravel Nova integration for the Zadarma VoIP/telephony platform. v2.0.0 is a production-readiness release, so the first thing to note is that it is a Nova package, not a generic Laravel package — the primary surface is a Nova tool/widget plus a webhook endpoint, and there is no meaningful headless use case.

Minimal setup:

1. composer require webard/nova-zadarma on a Laravel app with Nova installed, then php artisan nova:publish if you need to override the tool's assets.
2. Publish the package config (php artisan vendor:publish --tag=zadarma-config or vendor config group — check README.md, which was rewritten in v2) and populate Zadarma API key/secret and the webhook secret.
3. Exclude the webhook route from CSRF in VerifyCsrfToken (or the bootstrap/app.php equivalent on Laravel 11+), since Zadarma posts to it server-to-server.
4. Register the tool/card in app/Nova/Tools.php or NovaServiceProvider::cards() as directed by the README.
5. Point your Zadarma account's webhook URL at the route the package registers, then trigger a test call to confirm records land in the database.

Start by reading two files: the package's published config/zadarma.php (it is the authoritative list of options in v2 — the release added several) and the service provider, which shows the registered routes and Nova components. First practical use case: click-to-call from a Nova resource (e.g. an Order or Contact detail page) and inbound call logging via the webhook, which together cover the bulk of real deployments.

Implementation Patterns

Click-to-call as a Nova field or action. Attach the package's call field/action to the resource that holds the phone number. Keep the phone number in E.164 format in your model and let the package handle formatting — mixing formats is the fastest route to failed calls.

Webhook as the source of truth for call records. Treat the webhook handler as an event ingestion pipeline, not as a synchronous feature. v2's signed webhook verification means the request is validated before processing; persist the raw payload alongside the parsed call record so you can replay or backfill when mapping logic changes.

Wrap the webhook in your own listener. Rather than letting the package own all business logic, listen to whatever event it dispatches (or hook the model's created event) and fan out to your domain: link the call to a customer by phone match, create a CallLog activity, notify a sales channel. This keeps the package swappable.

Config-driven widget placement. v2 adds a widget position option; set it in config so the same codebase renders the widget consistently across environments rather than editing Blade per deployment.

Multi-tenant scoping. If you run one app for several tenants, resolve the Zadarma credentials per tenant and override the config at runtime (config(['zadarma.api_key' => ...])) inside a middleware or service provider boot — a single global key will leak calls across tenants.

Testing. Fake the HTTP layer toward Zadarma in feature tests and post a fixture payload at the webhook route to assert your downstream listeners run. Include a test for an invalid signature — that path is now explicit in v2 and is easy to regress.

Gotchas and Tips

• v2.0.0 is a major bump with no documented upgrade guide. The changelog says "refactored and cleaned," which strongly implies moved namespaces, renamed config keys, and possibly changed route paths. Diff the published config and the README against v1 before upgrading an existing install; do not assume config keys carried over.
• Webhook signature verification is new and fail-closed by design. If inbound calls stop being logged after upgrading, check the webhook secret first, then whether your proxy/CDN is stripping or rewriting headers. Log the raw request body before verification during rollout — verification almost always hashes the raw body, so middleware that mutates the payload will break it.
• Zadarma's API is not idempotent about webhook delivery. Retries are common; dedupe on the call/SMS identifier Zadarma sends rather than on your own auto-increment ID, or you will get duplicate call records.
• CSRF and route prefixing. The webhook route must be CSRF-exempt and, if you serve the app under a subdirectory or behind a path-rewriting proxy, the URL you give Zadarma must be the externally resolvable one. This is the single most common "nothing arrives" cause.
• Credentials belong in .env, not the published config. The config file should only read from env(); a committed key in a shared repo is a real exposure given the account-level access Zadarma keys carry.
• Debug by isolating layers. php artisan route:list | grep -i zadarma to confirm the route exists, then curl the endpoint locally with a signed fixture, then check storage/logs for the package's channel. Only after that blame Zadarma's dashboard.
• Extension points are thin. Expect the package to give you a Nova tool, a webhook controller, and config — not a full domain model. Budget time for your own call-log table, model, and Nova resource; do not fight the package to store business data it never intended to hold.
• Pin the version. Given a v2 rewrite, constrain to ^2.0 in composer.json and read the changelog on each minor bump; the "more config options" trend means defaults may shift.