Download the PHP package padosoft/laravel-rebel-channel-vonage without Composer

Laravel Rebel — Vonage Channel

Official documentation: https://doc.laravel-rebel.padosoft.com

Send phone verifications and SMS through Vonage, the Rebel way. This package plugs Vonage Verify (SMS / voice) and the Vonage SMS API into laravel-rebel-channels as a VerificationProvider and a MessageDeliveryChannel — so you get Vonage's global delivery plus Rebel's fraud guard, rate limiting, fallback and audit on top. Part of the padosoft/laravel-rebel-* suite.

Table of contents

• What it is
• Quick glossary
• Why this package
• Rebel + Vonage vs the alternatives
• Vonage dashboard setup (step by step)
• Installation
• Configuration
• Usage
• Delivery receipts (status webhook)
• Live tests against the real API
• .env.example
• Security notes
• Testing & License

What it is

A thin, well-tested Vonage provider for Rebel Channels. You don't call it directly — you call the Channels VerificationRouter, and it routes through this provider (with Rebel's bot gate, IRSF defences, per-number rate limit, fallback and audit around it).

It speaks two Vonage APIs:

• Vonage Verify — start + check one-time codes over SMS / voice. Vonage generates, sends and validates the OTP; you never store or generate the code yourself.
• Vonage SMS API — send a plain SMS (e.g. a transactional notification) as a MessageDeliveryChannel.

A small gateway seam (VonageGateway) wraps the HTTP calls, so the whole thing is unit-testable offline and has a real live test-suite for the actual API.

Depends on padosoft/laravel-rebel-core and padosoft/laravel-rebel-channels.

Quick glossary

Why this package

Rebel + Vonage vs the alternatives

Sending an OTP with Vonage, four ways:

Legend: ✅ built-in · ➖ partial / hosted-only · ❌ not available. Vonage is excellent at delivery; this package keeps all of that and adds the Rebel fraud/routing/audit layer around it. Shopify is a closed, hosted commerce platform: it sends its own customer OTPs but lets you neither pick Vonage as the sender, self-host it, fall back across vendors, nor configure its fraud controls — a black box, not a developer-facing verification library.

Vonage dashboard setup (step by step)

1. Create a Vonage account at dashboard.nexmo.com/sign-up. The free trial gives you a small credit — note that trial accounts can only send to whitelisted test numbers (add your test phone under Account → Test numbers).
2. Grab your credentials: on the dashboard home page copy your API key and API secret (top of the page).
3. (SMS sends only) decide your sender ID — an alphanumeric name (e.g. RebelApp, where alphanumeric senders are allowed) or a Vonage virtual number you rent under Numbers → Buy numbers. Put it in VONAGE_SMS_FROM.
4. (Delivery receipts) set the Delivery Receipts webhook URL (under Account → API settings → SMS settings, or per-application) to https://<your-host>/rebel/vonage/status (see below).
5. Put the values in your .env (see below). Done — the provider auto-registers.

Pricing: Vonage Verify is billed per successful verification + the channel cost; SMS is billed per segment. The free trial credit is enough to test end-to-end. Always keep the Rebel geo allowlist (in laravel-rebel-channels) tight to avoid IRSF charges.

Installation

Add your credentials to .env:

That's it — the provider registers itself into the Channels router under the key vonage.

Configuration

File config/rebel-channel-vonage.php:

Usage

Verification (the common case)

You typically don't touch this package directly — you use the Channels router:

Note: Vonage checks the code against the request_id returned by start() — not the phone number. Always store and pass back $start->reference. (Without it, check() fails closed with missing_reference.)

To force Vonage specifically, set it first in the Channels fallback order:

Plain SMS delivery

The provider also implements MessageDeliveryChannel, so you can send a transactional SMS:

Delivery receipts (status webhook)

Vonage knows whether an SMS was actually delivered, failed, and exactly how much it cost — but only it knows, unless you let it call you back. This package ships a delivery-receipt (DLR) webhook that turns those callbacks into Rebel audit events, so the admin panel's Channel Performance can show real delivered / failed rates and spend per channel.

What it records. On each callback the endpoint writes one audit event (recipient number stored only as a keyed HMAC, never in clear):

Each event carries channel: 'sms', provider: 'vonage', the HMAC'd recipient, and a metadata object:

It accepts both DLR shapes Vonage uses:

• the classic SMS-API DLR (msisdn, messageId, err-code, price), and
• the newer Messages-API status callback (to, message_uuid, usage.price, usage.currency).

(Vonage quotes price as a positive string; we store the absolute value so spend sums cleanly, and to stay consistent with the other Rebel channel providers. price/error_code are null when absent.)

Set the webhook URL. In the Vonage dashboard, point the Delivery Receipts callback at your app:

The endpoint is enabled by default (REBEL_VONAGE_WEBHOOK=true); set it to false to drop the route. The path is configurable via webhook.path.

Signature validation. The route has no auth middleware — Vonage posts server-to-server. Vonage only signs callbacks when you enable request signing on the account; once you do, set webhook.validate_signature=true and provide the signature_secret (and the matching signature_method). Every request must then carry a valid sig (recomputed from the sorted params

• your secret); a missing or forged signature is rejected with 403 and nothing is recorded. A malformed or empty payload is acknowledged with 204 and recorded as nothing, so a junk callback never 500s.

Build now, wire live later: the endpoint and its audit events exist today, so you can simulate Vonage callbacks (the test suite does exactly that) and the admin aggregates real delivered/cost data as soon as you set the DLR URL in Vonage.

Live tests against the real API

The offline suite uses a fake gateway. To exercise the real Vonage Verify API (tests/Live), opt in explicitly — it sends a real message:

Without REBEL_VONAGE_LIVE=1 or with any credential missing, the live tests self-skip, so composer test and external PRs never trigger a send. In CI, supply the values as secrets and set REBEL_VONAGE_LIVE=1 on a dedicated job.

.env.example

Security notes

• No client with empty keys: the Vonage gateway is only constructed when both the API key and secret are present.
• No exception leakage: transport errors are caught and returned as a generic provider_error — Vonage internals never bubble up to your app or logs.
• Explicit status mapping: only Vonage's 0 is treated as success; any unexpected status fails closed (no bogus "pending" with an empty reference).
• No PII in clear: the recipient number in delivery receipts is stored only as a keyed HMAC; OTPs and secrets are never logged.
• Keep IRSF defences on: pair this with the Channels geo allowlist / per-prefix cap to avoid premium-rate fraud charges.

🔋 Vibe coding with batteries included

This package ships AI batteries — so you (and your AI agent) can extend it correctly on the first try:

• CLAUDE.md — a concise AI working guide (purpose, conventions, architecture, how to extend, Definition of Done). Plain Markdown, so Claude Code, Cursor, Copilot and Codex all read it.
• AGENTS.md — the agent/workflow contract (branch → PR → CI → tag/release, the gates).
• .claude/skills/ — invocable skills (at least rebel-package-dev) encoding the suite's TDD loop, the PHPStan-level-max recipes, the security/telemetry rules, and the release discipline.

Open the repo in your AI editor and just start — the rules, guardrails and extension recipes come with it. PRs that follow the shipped CLAUDE.md pass CI (PHPStan max + Pest + Pint) and review the first time around.

Testing & License

License: MIT — see padosoft/laravel-rebel suite.