Receive Webhooks
Connect inbound messages and delivery updates to your application.
Choose the Events You Need
| Event | Purpose | Payload |
|---|---|---|
| Status update | Track processing, sending, delivery, reads, and failures | Status V1 |
| Inbound message | Receive SMS or RCS replies and interactions | Inbound V2 |
These are requests from Smobi to your server. The receiver examples are not endpoints you should call on api.smobi.com.
Configure Your Receiver
- Create an HTTPS endpoint in your application that accepts JSON POST requests.
- In the dashboard's webhook configuration for your brand, enter the inbound and/or status webhook URL.
- Select the payload version your receiver supports. This reference describes status V1 and inbound V2.
- Configure an authentication header for the receiver, such as
Authorization: Bearer YOUR_WEBHOOK_SECRET. Use a separate secret from your Smobi API key. - Send a test message to a phone you control and confirm the corresponding events reach your receiver.
Test phone numbers can have their own webhook URLs and headers. If events appear at an unexpected receiver, check the test-number overrides as well as the brand settings.
Authenticate Incoming Requests
Validate the custom authentication header before processing the body. Smobi sends the authentication headers configured for your receiver. Use those headers to authenticate the request; HMAC signature verification is not part of the documented webhook contract.
Process Reliably
Accept the event, persist or enqueue the work, then return a successful 2xx response promptly. Make processing idempotent and tolerate repeated or out-of-order status updates. For status events, keep smobiMessageId and clientRef to associate the event with your original request.
Automatic retry timing is not guaranteed by the public contract. Monitor receiver failures and delivery logs, and work with your Smobi representative to recover missed events when needed.
For inbound V2, use channel to choose sms or rcs. RCS replies may be text, media, location, or suggestion interactions; inspect the event subtype rather than assuming every reply is a text string.