renatoxm / laravel-vonage-dlr-webhooks
Handle delivery receipt SMS webhooks in Laravel php framework
Fund package maintenance!
RenatoXM
Requires
- php: ^8.1
- guzzlehttp/guzzle: ^7.8
- illuminate/http: ^10.0 || ^11.0
- illuminate/support: ^10.0 || ^11.0
- vonage/client-core: ^4.6
Requires (Dev)
- larastan/larastan: ^2.9
- laravel/pint: ^1.15
- orchestra/testbench: ^7.12 || ^8.17 || ^9.0
- phpunit/phpunit: ^9.4 || ^10.1
README
Handle Vonage DLR (delivery receipt) SMS webhooks in Laravel php framework. Take a look at contributing.md to see a to do list.
When you make a successful request to the SMS API, it returns an array of message objects, one for each message. Ideally these will have a status of 0, indicating success. But this does not mean that your message has reached your recipients. It only means that your message has been successfully queued for sending.
Vonage's adaptive routing then identifies the best carrier for your message. When the selected carrier has delivered the message, it returns a delivery receipt (DLR).
To receive DLRs in your application, you must provide a webhook for Vonage to send them to. Alternatively, you could use the Reports API to periodically download your records, including per-message delivery status.
Installation
Via Composer
composer require renatoxm/laravel-vonage-dlr-webhooks
Publish the config file with:
php artisan vendor:publish --provider="Renatoxm\LaravelVonageDlrWebhooks\LaravelVonageDlrWebhooksServiceProvider"
This package will log all incoming webhooks to the database by default.
Run the migrations to create a vonage_dlr_webhook_logs
table in the database:
php artisan migrate
Setup DLR (delivery receipt) webhooks from Vonage
Create your account at Nexmo and access the dashboard API settings.
Under SMS settings, choose SMS API, set the webhook format to POST-JSON
, and configure Delivery receipts (DLR) webhooks URL like this:
https://<you-domain.com>/api/webhooks/vonage/dlr
/api/webhooks/vonage/dlr
is the package's default endpoint.
You may change the
/api/webhooks/vonage/dlr
endpoint to anything you like.
You can do this by changing thepath
key in theconfig/laravel-vonage-dlr-webhooks.php
file.
Events
Whenever a webhook call comes in, this package will fire a LaravelVonageDlrWebhooksCalled
event.
You may register an event listener in the EventServiceProvider
:
/** * The event listener mappings for the application. * * @var array */ protected $listen = [ LaravelVonageDlrWebhooksCalled::class => [ YourListener::class, ], ];
Example of a listener:
<?php namespace App\Listeners; use Renatoxm\LaravelVonageDlrWebhooks\Events\LaravelVonageDlrWebhooksCalled; class YourListener { /** * Handle the event. * * @param \Renatoxm\LaravelVonageDlrWebhooks\Events\LaravelVonageDlrWebhooksCalled $event * @return void */ public function handle(LaravelVonageDlrWebhooksCalled $event) { // Do your work here. // $event->err_code // $event->message_id // $event->msisdn // ... } }
Advanced configuration
You may optionally publish the config file with:
php artisan vendor:publish --provider="Renatoxm\LaravelVonageDlrWebhooks\LaravelVonageDlrWebhooksServiceProvider" --tag="config"
Within the configuration file you may change the table name being used or the Eloquent model being used to save log records to the database.
If you want to use your own model to save the logs to the database you should extend the
Renatoxm\LaravelVonageDlrWebhooks\Model\LaravelVonageDlrWebhooksModel
class.
You can also exclude one or more event types from being logged to the database.
Place the events you want to exclude under the except
key:
'log' => [ ... 'except' => [ 'open', ... ], ],
All webhook requests will be logged in the vonage_dlr_webhook_logs
table.
Change log
Please see the changelog for more information on what has changed recently.
Testing
composer test
Contributing
Please see contributing.md for details and a todolist.
Security
If you discover any security issue, please email renatoxm[at]gmail[dot]com
instead of using the issue tracker.
Useful Links
Acknowledgment
This package is inspired by:
forked from https://github.com/mvdnbrk/laravel-postmark-webhooks
Credits
License
MIT. Please see the license file for more information.