Content-Type: application/json
{
"msisdn": "15035551234",
"sender": "28444",
"app_key": "1Drc_YYKTistxd0-p_Hljh",
"channel_id": "a828de17-b315-4e80-9d2d-35a906afeacf",
"mobile_originated_message": "balance",
"mobile_originated_id": "28883743-4868-4083-ab5d-77ac4542531a",
"received_timestamp": "2019-04-29T12:00:01.492",
"operator_timestamp": "2019-04-29T11:58:13.100"
}
```
* `msisdn` (string) – The [MSISDN](https://www.airship.com/docs/reference/glossary/#msisdn) of the audience member (mobile device) who sent the mobile-originated message.
* `sender` (string) – The [Sender ID](https://www.airship.com/docs/reference/glossary/#sender_id) that received the mobile-originated message. This is important if you have more than one sender.
* `app_key` (string) – The app key that the sender is configured for.
* `channel_id` (string) – (Optional) The channel ID associated with the MSISDN/sender. You can use this value to make opt-in, opt-out, or tag changes. If a channel does not exist for the MSISDN/sender and the keyword is not configured to create a channel if none exists, this field is absent.
* `mobile_originated_message` (string) – The contents of the mobile-originated message; this message consists of, or contains, a keyword.
* `mobile_originated_id` (string) – A unique ID for the message. Use this ID to respond to the mobile-originated message.
* `received_timestamp` (string) — An ISO 8601 UTC timestamp of the current time (the time of the webhook request). This represents the beginning of a 10-minute window to send a response to the `mobile_originated_id`.
* `operator_timestamp` (string) — An ISO 8601 UTC timestamp of when the mobile-originated message was originally sent, according to the carrier or aggregator.
> **Note:** Due to carrier maintenance and delays outside of Airship's control, mobile-originated messages can arrive at the webhook significantly after they are sent from the device (represented by the `operator_timestamp`). You may want to alter your messaging if a mobile-originated message is not received in a timely manner.
### Webhook Signature Hash Security {#signature-security}
Rather than basic authentication, you can configure
a signature that your webhook server can use to verify that requests come from Airship. To enable this signature, select Signature Hash authorization and set a secret_key when configuring your webhook or open channel.
When you enable and set a secret_key, outgoing requests include a hash-based
authentication code computed using the sha256 hash function in an X-UA-SIGNATURE header. You can use this same algorithm to verify the signature
on the receiving server.
X-UA-SIGNATURE is composed of the secret_key and a message, both of
which must be UTF-8 encoded. The message is a concatenation of the following
string values:
- The
X-UA-TIMESTAMP header — the unix timestamp when the request was sent.
- The
: character.
- The JSON request body.
To prevent replay attacks, you should validate the X-UA-TIMESTAMP within a threshold of the current time. We recommend that you use a 5-minute threshold to account for time drift, though Airship uses NTP and we recommend that your webhook server does the same. To prevent timing attacks, you should employ a constant time-compare function when checking signatures.
**Request headers with secret key**
```http
POST /yourWebhookServer/push HTTP/1.1
Content-Type: application/vnd.urbanairship+json; version=3
Content-encoding: gzip
X-UA-TIMESTAMP: 1536947409
X-UA-SIGNATURE: 68688b9dbd5c381851d3cd51dba3093c6633ceef58e6fee6ad4757f857f59aea
Data-Attribute: values
```
## Sending Custom Responses to Mobile-Originated Messages
You can issue custom SMS or MMS responses to mobile-originated messages using the `mobile_originated_id`. You have 10 minutes from the `received_timestamp` to respond to a mobile-originated message; the `mobile_originated_id` expires after 10 minutes.
The `/sms/custom-response` API uses Bearer Token authorization. You must create a token with the **All Access** role to send custom responses. See [Creating bearer tokens](https://www.airship.com/docs/guides/getting-started/developers/api-security/#creating-bearer-tokens) in *Airship API Security*.
```http
POST /api/sms/custom-response HTTP/1.1
Authorization: Bearer
X-UA-Appkey:
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json
{
"sms" : {
"alert": "Your balance is $12.34"
},
"mobile_originated_id" : "28883743-4868-4083-ab5d-77ac4542531a"
}
```