Inbound message and message status webhooks
You need to configure both your Inbound Message and Message Status webhooks.
Configure your webhook URLs
There are at least two webhooks you must configure:
- Message Status webhook
- Inbound Message webhook
When messages status updates are generated, such as delivered, rejected or accepted, callbacks will be received on the Message Status webhook URL.
When an inbound message is received, a callback with message payload is invoked on the Inbound Message webhook URL.
IMPORTANT: Both webhook URLs should be configured. At the very least your webhook handlers should return 200 responses for both Inbound Message and Message Status callbacks. This ensures potential callback queuing issues are avoided.
To configure the webhook URLs
If you have already created an application, but not yet configured your webhooks, go to Your Applications and select the application to configure.
Click Edit to modify the application's webhook URLs.
In the Messages capabilities section, enter your webhook URLs in the fields labeled Status URL and Inbound URL.
The values you enter for webhook URLs depends on where your webhook server is located. For example:
| Webhook | URL |
|---|---|
| Status URL | https://www.example.com/webhooks/message-status |
| Inbound URL | https://www.example.com/webhooks/inbound-message |
NOTE: We recommend using JWT-based auth as this allows you to configure your inbound and delivery receipt webhook URLs at the application-level. Otherwise, all callbacks from your different applications will be sent to your account-level webhook URLs.
NOTE: The callbacks are sent over POST HTTP requests.
Testing locally via Ngrok
If you want to test your application locally you can use Ngrok.
See our information on Using Ngrok for local development
If using Ngrok in this manner you would use the Ngrok URLs for your webhook URLs:
https://abcdef1.ngrok.io/webhooks/inbound-messagehttps://abcdef1.ngrok.io/webhooks/message-status
Webhook queue
Please note that webhooks emanating from Vonage, such as those on your Message Status webhook URL and Inbound Message URL, are queued by Vonage on a per-message basis.
Please ensure that all applications acknowledge webhooks with a 200 response.
Signed webhooks
In order to validate the origin of your webhooks, you can validate the signature of the webhooks, see instructions here
Webhooks in production use
If the Webhook URLs for messages in your Vonage API Account are already in production use and you would like a second one for using the Messages API, please email support and ask for a sub API Key.