Introduction
httpSMS uses webhooks to push real-time notifications to your application about SMS events for example when an SMS is received by your Android you will get a notification about this event.
Last updated
Was this helpful?
httpSMS uses webhooks to push real-time notifications to your application about SMS events for example when an SMS is received by your Android you will get a notification about this event.
Last updated
Was this helpful?
You will need the following to receive webhooks with httpSMS.
Callback URL - httpSMS will send a POST
to this URL every time an event is triggered. This
Signing Key - When httpSMS sends a POST
request to your endpoint, you can use the signing key to verify that the request is actually coming from the httpSMS server. The signing key is a random string that will be used to create a .
Events - This is the list of httpSMS events that will be forwarded to your callback URL. We support only the following events at the moment
message.phone.received
- This event is emitted when your Android phone receives a new SMS
message.phone.sent
- This event is emitted when the httpSMS app on your phone sends out an SMS.
message.phone.delivered
- This event is emitted when an SMS is delivered to the recipient's phone.
message.send.failed
- This event is emitted when an SMS fails to be sent out by your Android phone
message.send.expired
- This event is emitted when an SMS expires before being sent out by your Android phone.
message.send.expired
- This event is emitted when an SMS expires before being sent out by your Android phone.
message.call.missed
- This event is emitted when your Android phone receives a missed phone call.
phone.heartbeat.offline
- This event is emitted when the httpSMS server did not get a heartbeat (ping) from your Android phone in the last 1 hour.
phone.heartbeat.online
- This event is emitted when the httpSMS server receives a heartbeat (ping) from your Android phone after it was previously offline.
Phone Numbers - This is the list of phone numbers whose events you want to listen to. You can have multiple phone numbers on your account but you can also configure the webhook to listen to events only for a subset of your phone numbers.
When a webhook event occurs in httpSMS, a POST
request will be sent to your configured callbackURL
.
Each webhook request from httpSMS has a timeout of 5
seconds so ensure that you can process webhook requests as fast as possible. Return a 200
response code to show that the webhook event was processed successfully.
If your server responds with a 5XX
status code, the webhook request will be retried a maximum of 4 times with at least a 1 second delay between each retry.
Each webhook request from httpSMS will contain the following headers
X-Event-Type
- This is the name of the event. e.g in the case of a message received on the Android phone, the X-Event-Type will be `message.phone.received
Content-Type
- This will always be application/json
We have written sample code to receive webhook events on your server on popular programing languages and frameworks, you can copy and inspect the code for your inspiration from GitHub.
Laravel - PHP
Express - JS
Authorization
- Every webhook request made by httpSMS will contain a JWT Bearer token signed with the HS256
algorithm and the signing key which you set when you created the webhook. We recommend you use a popular to validate this token.
httpSMS uses internally so every webhook request payload will be a valid cloud event serialized as JSON. You can use a popular to validate and process the webhook request payload. You can see the list of .