# Introduction
## 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](https://jwt.io/introduction).
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.
{% hint style="info" %}
Webhooks can be set up and managed from [Settings > Webhooks](https://httpsms.com/settings#webhooks)[ ](https://httpsms.com/settings)in your httpSMS dashboard or programmatically [using the httpSMS API](https://api.httpsms.com/index.html#/Webhooks/post_webhooks).
{% endhint %}
## 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](https://jwt.io/libraries) to validate this token.
* `Content-Type` - This will always be `application/json`
### Webhook Request Body
httpSMS uses [CloudEvents ](https://cloudevents.io/)internally so every webhook request payload will be a valid cloud event serialized as JSON. You can use a popular [cloudevent SDK](https://github.com/cloudevents/spec#sdks) to validate and process the webhook request payload. You can see the list of [webhook events with their payload on the Events page](https://docs.httpsms.com/webhooks/events).
### 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.
