# Webhooks

Here you can see the data sent in notification requests to your customer-provided endpoints. The only requirement for a customer-defined endpoint is that it responds with a <mark style="color:green;">`200`</mark> HTTP status code.

Webhooks must first be registered, see [setting-up-your-first-webhook](https://developers.mobile-text-alerts.com/tutorials/webhooks/setting-up-your-first-webhook "mention") to learn more.

<a href="../api-reference/webhooks" class="button primary" data-icon="webhook">Webhooks API Reference</a>

## Webhooks Event Payloads

{% hint style="info" %}
**Optional Fields**

Some fields may not always be included in the webhook payload. These are indicated with: **\***. These fields may be missing from the payload or have a `NULL` value.

All other fields below are always expected in the webhook payload.
{% endhint %}

The payloads documented below describe the data sent to the endpoints you (as a Mobile Text Alerts customer) must implement to successfully receive notifications.

**Versions**

Our latest webhook version is V3. If you haven't specifically requested an earlier version, you will receive the V3 payloads. Previous versions (V1, V2) are also included below.

**Formats**\
Dynamic fields may also include the following format specifications:

* `phone_national` - A phone number in the national format. (*Ex:* `5555555555`)
* `phone_e164` - A phone number in E.164 format. (*Ex:* `[+] [country code] [subscriber number including area code]`, max 15 digits)
* `enum` - A field with a pre-defined list of values.
* `date` - A date string. The timezone and format are specified.

**Tags**

Many of the payloads below include an optional `tags` field. This is an object of tags provided by the customer when the message was sent.

*Example:*

```json
{
  "tags": {
    "key": "value"
  }
}
```

### Delivery Status

<details>

<summary>V1 Delivery Status Payload</summary>

<table><thead><tr><th width="190">Field</th><th width="180">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>destinationNumber</code></td><td><code>string</code></td><td>The number the message was sent to.</td></tr><tr><td><code>messageId</code></td><td><code>number</code></td><td>The MTA internal id of the outbound message.</td></tr><tr><td><code>externalId</code></td><td><code>string</code></td><td>The id provided by the customer when the message was sent.</td></tr><tr><td><code>status</code></td><td><code>MTADeliveryStatus</code></td><td>The delivery status. See <a href="#mta-delivery-status-codes">MTA Delivery Status Codes</a>.</td></tr><tr><td><code>tags</code> *</td><td><code>&#x3C;string, string></code></td><td>An object of any tags provided by the customer when the message was sent.</td></tr><tr><td><code>senderName</code> *</td><td><code>string</code></td><td>The sender name used to pre-populate the "To:" field for iMessages.</td></tr><tr><td><code>type</code></td><td><code>MTAWebhook.DELIVERY_STATUS</code></td><td>The webhook event type, identifying it as delivery status.</td></tr></tbody></table>

</details>

<details>

<summary>V2 Delivery Status Payload</summary>

<table><thead><tr><th width="190">Field</th><th width="180">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>destinationNumber</code></td><td><code>string</code></td><td>The number the message was sent to.</td></tr><tr><td><code>messageId</code></td><td><code>number</code></td><td>The MTA internal id of the outbound message.</td></tr><tr><td><code>externalId</code></td><td><code>string</code></td><td>The id provided by the customer when the message was sent.</td></tr><tr><td><code>status</code></td><td><code>MTADeliveryStatus</code></td><td>The delivery status. See <a href="#mta-delivery-status-codes">MTA Delivery Status Codes</a>.</td></tr><tr><td><code>tags</code> *</td><td><code>&#x3C;string, string></code></td><td>An object of any tags provided by the customer when the message was sent.</td></tr><tr><td><code>senderName</code> *</td><td><code>string</code></td><td>The sender name used to pre-populate the "To:" field for iMessages.</td></tr><tr><td><code>type</code></td><td><code>MTAWebhook.DELIVERY_STATUS</code></td><td>The webhook event type, identifying it as delivery status.</td></tr></tbody></table>

</details>

<details>

<summary>V3 Delivery Status Payload</summary>

<table><thead><tr><th width="190">Field</th><th width="180">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>fromNumber</code> *</td><td><code>string</code> |<code>phone_e164</code></td><td>The number that the message was sent from.</td></tr><tr><td><code>toNumber</code></td><td><code>string</code> |<code>phone_e164</code></td><td>The number the message was sent to.</td></tr><tr><td><code>messageId</code></td><td><code>string</code></td><td>The MTA internal id of the outbound message.</td></tr><tr><td><code>externalId</code> *</td><td><code>string</code></td><td>The id provided by the customer when the message was sent.</td></tr><tr><td><code>timestamp</code></td><td><code>string</code> | <code>date:UTC:ISO-8601</code></td><td>A date string. The timezone and format are specified.</td></tr><tr><td><code>status</code></td><td><code>number</code> |<code>MTADeliveryStatus</code></td><td>The delivery status code. See <a href="#mta-delivery-status-codes">MTA Delivery Status Codes</a>.</td></tr><tr><td><code>tags</code> *</td><td><code>&#x3C;string, string></code></td><td>An object of any tags provided by the customer when the message was sent.</td></tr><tr><td><code>senderName</code> *</td><td><code>string</code></td><td>The sender name used to pre-populate the "To:" field for iMessages.</td></tr><tr><td><code>type</code></td><td><code>MTADeliveryStatus</code></td><td>The webhook event type, identifying it as delivery status.</td></tr></tbody></table>

</details>

#### Mobile Text Alerts Delivery Status Codes

One of the fields in the delivery-status webhook is `status`. It returns a code associated with the following statuses:

{% code overflow="wrap" %}

```
QUEUED = 1,
SENDING = 2,
SENT = 3, // provider sent to carrier
DELIVERED = 4,
SENDING_FAILED = 5, // something failed on the provider end
DELIVERY_FAILED = 6, // sent to carrier, but failed to deliver
DELIVERY_UNCONFIRMED = 7, // no response from carrier
DELIVERY_REJECTED = 8, // blocked by carrier
UNDELIVERED = 9, // handset is turned off, out of coverage, or something else of that nature
INVALID_NUMBER = 10,
STOPPED_NUMBER = 11,
LANDLINE = 12,
SEND_REJECTED = 13, // blocked by provider
QUEUEING_FAILED = 14 // carrier failed to acknowledge message
```

{% endcode %}

### Message Reply

<details>

<summary>V1 Message Reply Payload</summary>

<table><thead><tr><th width="190">Field</th><th width="180">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>originationNumber</code></td><td><code>string</code></td><td>The number that the inbound message was sent from.</td></tr><tr><td><code>destinationNumber</code></td><td><code>number</code></td><td>The number that the inbound message was sent to.</td></tr><tr><td><code>message</code></td><td><code>string</code></td><td>The content of the inbound message.</td></tr><tr><td><code>messageId</code></td><td><code>number</code></td><td>The internal MTA id for the inbound message.</td></tr><tr><td><code>externalId</code></td><td><code>string</code></td><td>The customer provided id from the last outbound message sent to the origination number.</td></tr><tr><td><code>previousMessageId</code></td><td><code>string</code></td><td>The internal MTA id for the last interaction with the outbound number. This could be an outbound id or an inbound id, whichever happened last.</td></tr><tr><td><code>isOptOutMessage</code></td><td><code>boolean</code></td><td>If <code>true</code>, indicates the inbound message is considered an opt-out request.</td></tr><tr><td><code>tags</code> *</td><td><code>&#x3C;string, string></code></td><td>An object of any tags provided by the customer from the last outbound message sent to the origination number.</td></tr><tr><td><code>url</code> *</td><td><code>string</code></td><td>The URL of the message, if it was an MMS and had an image attached.</td></tr><tr><td><code>senderName</code> *</td><td><code>string</code></td><td>The sender name used to pre-populate the "To:" field for iMessages.</td></tr><tr><td><code>type</code></td><td><code>MTAWebhook.MESSAGE_REPLY</code></td><td>The webhook event type, identifying it as message reply.</td></tr></tbody></table>

</details>

<details>

<summary>V2 Message Reply Payload</summary>

<table><thead><tr><th width="190">Field</th><th width="180">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>originationNumber</code></td><td><code>string</code></td><td>The number that the inbound message was sent from.</td></tr><tr><td><code>destinationNumber</code></td><td><code>string</code></td><td>The number that the inbound message was sent to.</td></tr><tr><td><code>message</code></td><td><code>string</code></td><td>The content of the inbound message.</td></tr><tr><td><code>messageId</code></td><td><code>number</code></td><td>The internal MTA id for the inbound message.</td></tr><tr><td><code>externalId</code></td><td><code>string</code></td><td>The customer provided id from the last outbound message sent to the origination number.</td></tr><tr><td><code>previousMessageId</code></td><td><code>string</code></td><td>The internal MTA id for the last interaction with the outbound number. This could be an outbound id or an inbound id, whichever happened last.</td></tr><tr><td><code>isOptOutMessage</code></td><td><code>boolean</code></td><td>If <code>true</code>, indicates the inbound message is considered an opt-out request.</td></tr><tr><td><code>tags</code> *</td><td><code>&#x3C;string, string></code></td><td>An object of any tags provided by the customer from the last outbound message sent to the origination number.</td></tr><tr><td><code>url</code> *</td><td><code>string</code></td><td>The URL of the message, if it was an MMS and had an image attached.</td></tr><tr><td><code>senderName</code> *</td><td><code>string</code></td><td>The sender name used to pre-populate the "To:" field for iMessages.</td></tr><tr><td><code>type</code></td><td><code>MTAWebhook.MESSAGE_REPLY</code></td><td>The webhook event type, identifying it as message reply.</td></tr></tbody></table>

</details>

<details>

<summary>V3 Message Reply Payload</summary>

<table><thead><tr><th width="190">Field</th><th width="180">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>fromNumber</code></td><td><code>string</code> |<code>phone_e164</code></td><td>The number that the inbound message was sent from.</td></tr><tr><td><code>toNumber</code> *</td><td><code>string</code> |<code>phone_e164</code></td><td>The number that the inbound message was sent to.</td></tr><tr><td><code>replyId</code></td><td><code>string</code></td><td>The MTA internal id of the message reply.</td></tr><tr><td><code>externalId</code> *</td><td><code>string</code></td><td>The customer provided id from the last outbound message sent to the origination number.</td></tr><tr><td><code>message</code></td><td><code>string</code></td><td>The content of the inbound message.</td></tr><tr><td><code>messageId</code> *</td><td><code>number</code></td><td>The internal MTA id for the inbound message.</td></tr><tr><td><code>url</code> *</td><td><code>string</code></td><td>The URL of the message, if it was an MMS and had an image attached.</td></tr><tr><td><code>timestamp</code></td><td><code>string</code> | <code>date:UTC:ISO-8601</code></td><td>A date string. The timezone and format are specified.</td></tr><tr><td><code>tags</code> *</td><td><code>&#x3C;string, string></code></td><td>An object of any tags provided by the customer from the last outbound message sent to the origination number.</td></tr><tr><td><code>senderName</code> *</td><td><code>string</code></td><td>The sender name used to pre-populate the "To:" field for iMessages.</td></tr></tbody></table>

</details>

### Message Send

<details>

<summary>V1 Message Send Payload</summary>

<table><thead><tr><th width="190">Field</th><th width="179.5">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>destinationNumber</code></td><td><code>string</code></td><td>The number the message was sent to.</td></tr><tr><td><code>messageId</code></td><td><code>string</code> | <code>number</code></td><td>The MTA internal id of the outbound message.</td></tr><tr><td><code>externalId</code></td><td><code>string</code></td><td>The id provided by the customer when the message was sent.</td></tr><tr><td><code>message</code></td><td><code>string</code></td><td>The content of the outbound message.</td></tr><tr><td><code>url</code></td><td><code>string</code></td><td>The URL of the message, if it was an MMS and had an image attached.</td></tr><tr><td><code>tags</code> *</td><td><code>&#x3C;string, string></code></td><td>An object of any tags provided by the customer when the message was sent.</td></tr><tr><td><code>senderName</code> *</td><td><code>string</code></td><td>The sender name used to pre-populate the "To:" field for iMessages.</td></tr><tr><td><code>type</code></td><td><code>MTAWebhook.MESSAGE_SEND</code></td><td>The webhook event type, identifying it as message send.</td></tr></tbody></table>

</details>

<details>

<summary>V2 Message Send Payload</summary>

<table><thead><tr><th width="190">Field</th><th width="180">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>destinationNumber</code></td><td><code>string</code></td><td>The number the message was sent to.</td></tr><tr><td><code>messageId</code></td><td><code>number</code></td><td>The MTA internal id of the outbound message.</td></tr><tr><td><code>externalId</code></td><td><code>string</code></td><td>The id provided by the customer when the message was sent.</td></tr><tr><td><code>message</code></td><td><code>string</code></td><td>The content of the outbound message.</td></tr><tr><td><code>url</code></td><td><code>string</code></td><td>The URL of the message, if it was an MMS and had an image attached.</td></tr><tr><td><code>tags</code> *</td><td><code>&#x3C;string, string></code></td><td>An object of any tags provided by the customer when the message was sent.</td></tr><tr><td><code>senderName</code> *</td><td><code>string</code></td><td>The sender name used to pre-populate the "To:" field for iMessages.</td></tr><tr><td><code>type</code></td><td><code>MTAWebhook.MESSAGE_SEND</code></td><td>The webhook event type, identifying it as message send.</td></tr></tbody></table>

</details>

<details>

<summary>V3 Message Send Payload</summary>

<table><thead><tr><th width="190">Field</th><th width="180">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>fromNumber</code> *</td><td><code>string</code> |<code>phone_e164</code></td><td>The number that the message was sent from.</td></tr><tr><td><code>toNumber</code></td><td><code>string</code> |<code>phone_e164</code></td><td>The number the message was sent to.</td></tr><tr><td><code>messageId</code></td><td><code>string</code></td><td>The MTA internal id of the outbound message.</td></tr><tr><td><code>externalId</code> *</td><td><code>string</code></td><td>The id provided by the customer when the message was sent.</td></tr><tr><td><code>message</code></td><td><code>string</code></td><td>The content of the outbound message.</td></tr><tr><td><code>url</code> *</td><td><code>string</code></td><td>The URL of the message, if it was an MMS and had an image attached.</td></tr><tr><td><code>timestamp</code></td><td><code>string</code> | <code>date:UTC:ISO-8601</code></td><td>A date string. The timezone and format are specified.</td></tr><tr><td><code>tags</code> *</td><td><code>&#x3C;string, string></code></td><td>An object of any tags provided by the customer when the message was sent.</td></tr><tr><td><code>senderName</code> *</td><td><code>string</code></td><td>The sender name used to pre-populate the "To:" field for iMessages.</td></tr></tbody></table>

</details>

### Number Opt-In

<details>

<summary>V1 Number Opt-In Payload</summary>

<table><thead><tr><th width="190">Field</th><th width="180">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>originationNumber</code></td><td><code>string</code></td><td>The number the message was sent from.</td></tr><tr><td><code>destinationNumber</code></td><td><code>string</code></td><td>The number the message was sent to.</td></tr><tr><td><code>senderName</code> *</td><td><code>string</code></td><td>The sender name used to pre-populate the "To:" field for iMessages.</td></tr><tr><td><code>optInType</code></td><td><code>enum</code> <code>NumberOptInType</code></td><td>Identifies how the method used to opt-in, see <a href="#number-opt-in-types">Number Opt-In Types</a>.</td></tr><tr><td><code>type</code></td><td><code>type: MTAWebhook.NUMBER_OPT_IN</code></td><td>The webhook event type, identifying it as number opt-in.</td></tr></tbody></table>

</details>

<details>

<summary>V2 Number Opt-In Payload</summary>

<table><thead><tr><th width="189.5">Field</th><th width="180">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>originationNumber</code></td><td><code>string</code></td><td>The number the message was sent from.</td></tr><tr><td><code>destinationNumber</code> *</td><td><code>string</code></td><td>The number the message was sent to.</td></tr><tr><td><code>senderName</code> *</td><td><code>string</code></td><td>The sender name used to pre-populate the "To:" field for iMessages.</td></tr><tr><td><code>optInType</code></td><td><code>enum</code> <code>NumberOptInType</code></td><td>Identifies how the method used to opt-in, see <a href="#number-opt-in-types">Number Opt-In Types</a>.</td></tr><tr><td><code>type</code></td><td><code>MTAWebhook.NUMBER_OPT_IN</code></td><td>The webhook event type, identifying it as number opt-in.</td></tr></tbody></table>

</details>

<details>

<summary>V3 Number Opt-In Payload</summary>

<table><thead><tr><th width="189.5">Field</th><th width="180">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>fromNumber</code></td><td><code>string</code></td><td>The number the message was sent from.</td></tr><tr><td><code>toNumber</code> *</td><td><code>string</code></td><td>The number the message was sent to.</td></tr><tr><td><code>senderName</code> *</td><td><code>string</code></td><td>The sender name used to pre-populate the "To:" field for iMessages.</td></tr><tr><td><code>type</code></td><td><code>enum NumberOptInType</code></td><td>The webhook event type, identifying it as number opt-in.</td></tr><tr><td><code>timestamp</code></td><td><code>string</code> | <code>date:UTC:ISO-8601</code></td><td>A date string. The timezone and format are specified.</td></tr></tbody></table>

</details>

#### Number Opt-In Types

One of the fields in the number opt-in webhook is `optInType`. It returns one of the following values, which indicates the method used to opt in:

```
enum NumberOptInType {
    SMS = 'sms',
    EMAIL = 'email',
    IMessage = 'imessage',
    RCS = 'rcs',
}
```