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.

Creating Webhooks

You will need the following to receive webhooks with httpSMS.

1. Callback URL - httpSMS will send a POST to this URL every time an event is triggered. This

2. 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 JWT auth token.

3. 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.

4. 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.

Webhooks can be set up and managed from Settings > Webhooks in your httpSMS dashboard or programmatically using the httpSMS API.

Webhook Request

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.

Webhook Request Headers

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

• 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 JWT library to validate this token.
• Content-Type - This will always be application/json

Webhook Request Body

httpSMS uses CloudEvents internally so every webhook request payload will be a valid cloud event serialized as JSON. You can use a popular cloudevent SDK to validate and process the webhook request payload. You can see the list of webhook events with their payload on the Events page.

Recipes

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.

Framework	Code
Laravel - PHP	https://github.com/NdoleStudio/httpsms-recipes/tree/main/laravel
Express - JS	https://github.com/NdoleStudio/httpsms-recipes/tree/main/express