- 15 Oct 2024
- 2 Minutes to read
Webhooks for Transactional SMS
- Updated on 15 Oct 2024
- 2 Minutes to read
A webhook is a service that enables data to be sent from one program to another as soon as a specific event occurs. Because communication is started by the application giving the data rather than the one receiving it, webhooks are frequently referred to as reverse APIs.
A webhook offers several key benefits:
- Track user-level details such as delivered, open, click, and unsubscribed.
- Synced and consistent database of real-time user interactions with SMS.
- Webhooks SMS reporting (invalid SMS IDs, drops) for improved list/database hygiene.
- Automatic and manual user segmentation using SMS events in your own CRM.
Set Up Webhook
You can set up the callback within the body payload to receive webhook events for your transactional SMS by adding the following sample object at the end of the payload:
{
"callback": {
"url": "https://yourdomain/9c99bc26-373e-4847-b725-d7103803c111"
}
}
Webhook Events
Whenever there is an event, webhook events will notify a URL of your choice via HTTPS POST. Webhook events will provide information about the event, and return a unique message ID (msg-id) generated to map the SMS associated with the event while also hitting the API. Webhook events will be delivered to the provided endpoint.
The following are some of the most essential events:
- Sent
- Delivered
- Carrier Violation
- Hard Bounce
- Soft Bounce
- Unknown Delivery
Sent
A sent event is triggered when a message has been received and is ready to be delivered to the recipient.
{
"id": "sms-66944540-5ade",
"uniqueArgs": {
"param1": "test 1",
"param2": "test 2"
},
"event": "sent",
"partCount": 1
}
Delivered
A delivered event is triggered when a message is delivered to the recipient.
{
"id": "sms-66944540-5ade",
"uniqueArgs": {
"param1": "test 1",
"param2": "test 2"
},
"event": "delivered"
}
Carrier Violation
A carrier violation event occurs when the messages are undelivered due to content or spam filtering by the service provider.
{
"id": "sms-66944540-5ade",
"uniqueArgs": {
"param1": "test 1",
"param2": "test 2"
},
"event": "undelivered",
"reason": {
"message": "Carrier Violation",
"code": 1408
}
}
Hard Bounce
A hard bounce event occurs when the messages are undelivered since the recipients’ phone numbers are not in use.
{
"id": "sms-66944540-5ade",
"uniqueArgs": {
"param1": "test 1",
"param2": "test 2"
},
"event": "undelivered",
"reason": {
"message": "Hard Bounce",
"code": 1400
}
}
Soft Bounce
A soft bounce event occurs when the messages are undelivered since the recipients are not reachable at that moment.
{
"id": "sms-66944540-5ade",
"uniqueArgs": {
"param1": "test 1",
"param2": "test 2"
},
"event": "undelivered",
"reason": {
"message": "Soft Bounce",
"code": 1404
}
}
Unknown Delivery
An unknown delivery occurs when the messages can’t be confirmed as Delivered by the service provider due to uncertain reasons.
{
"id": "sms-66944540-5ade",
"uniqueArgs": {
"param1": "test 1",
"param2": "test 2"
},
"event": "undelivered",
"reason": {
"message": "Soft Bounce",
"code": 1409
}
}