# 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](/tutorials/webhooks/setting-up-your-first-webhook.md) to learn more.

<a href="/pages/uWxEX5m9f4m2HKQjSQvr" 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',
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.mobile-text-alerts.com/tutorials/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.