Webhooks

View the expected webhook event payloads to your custom defined endpoints

Here you can see the data that is sent in notification requests to your customer provided endpoints. The only requirement for a customer defined endpoint is that the response has a 200 HTTP status code.

Webhooks first must be registered, see Setting up Webhooks to learn more.

Webhooks Event Payloads

Optional Fields

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

All other fields below are always expected in the webhook payload.

The payloads documented below describe the expected data to the endpoints you (as an MTA customer) must implement in order to successfully receive notifications.

Versions

Our latest webhook version is V3. If you haven't specifically requested to use or remain on an earlier version, you will receive this latest version of 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 E164 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 the following payloads have the optional tags field which is an object of any tags provided by the customer when the message was sent.

Example:

    "tags": {
        "key": "value"
    }

Delivery Status

V1 Delivery Status Payload

Field	Type	Description
destinationNumber	string	The number the message was sent to.
messageId	number	The MTA internal id of the outbound message.
externalId	string	The id provided by the customer when the message was sent.
status	MTADeliveryStatus	The delivery status. See MTA Delivery Status Codes.
tags *	<string, string>	An object of any tags provided by the customer when the message was sent.
senderName *	string	The sender name used to pre-populate the "To:" field for iMessages.
type	MTAWebhook.DELIVERY_STATUS	The webhook event type, identifying it as delivery status.

V2 Delivery Status Payload

Field	Type	Description
destinationNumber	string	The number the message was sent to.
messageId	number	The MTA internal id of the outbound message.
externalId	string	The id provided by the customer when the message was sent.
status	MTADeliveryStatus	The delivery status. See MTA Delivery Status Codes.
tags *	<string, string>	An object of any tags provided by the customer when the message was sent.
senderName *	string	The sender name used to pre-populate the "To:" field for iMessages.
type	MTAWebhook.DELIVERY_STATUS	The webhook event type, identifying it as delivery status.

V3 Delivery Status Payload

Field	Type	Description
fromNumber *	string |phone_e164	The number that the message was sent from.
toNumber	string |phone_e164	The number the message was sent to.
messageId	string	The MTA internal id of the outbound message.
externalId *	string	The id provided by the customer when the message was sent.
timestamp	string | date:UTC:ISO-8601	A date string. The timezone and format are specified.
status	number |MTADeliveryStatus	The delivery status code. See MTA Delivery Status Codes.
tags *	<string, string>	An object of any tags provided by the customer when the message was sent.
senderName *	string	The sender name used to pre-populate the "To:" field for iMessages.
type	MTADeliveryStatus	The webhook event type, identifying it as delivery status.

MTA Delivery Status Codes

One of the fields of the delivery status webhook is status which will return a code that is associated with the following statuses:

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

Message Reply

V1 Message Reply Payload

Field	Type	Description
originationNumber	string	The number that the inbound message was sent from.
destinationNumber	number	The number that the inbound message was sent to.
message	string	The content of the inbound message.
messageId	number	The internal MTA id for the inbound message.
externalId	string	The customer provided id from the last outbound message sent to the origination number.
previousMessageId	string	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.
isOptOutMessage	boolean	If true, indicates the inbound message is considered an opt-out request.
tags *	<string, string>	An object of any tags provided by the customer from the last outbound message sent to the origination number.
url *	string	The URL of the message, if it was an MMS and had an image attached.
senderName *	string	The sender name used to pre-populate the "To:" field for iMessages.
type	MTAWebhook.MESSAGE_REPLY	The webhook event type, identifying it as message reply.

V2 Message Reply Payload

Field	Type	Description
originationNumber	string	The number that the inbound message was sent from.
destinationNumber	string	The number that the inbound message was sent to.
message	string	The content of the inbound message.
messageId	number	The internal MTA id for the inbound message.
externalId	string	The customer provided id from the last outbound message sent to the origination number.
previousMessageId	string	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.
isOptOutMessage	boolean	If true, indicates the inbound message is considered an opt-out request.
tags *	<string, string>	An object of any tags provided by the customer from the last outbound message sent to the origination number.
url *	string	The URL of the message, if it was an MMS and had an image attached.
senderName *	string	The sender name used to pre-populate the "To:" field for iMessages.
type	MTAWebhook.MESSAGE_REPLY	The webhook event type, identifying it as message reply.

V3 Message Reply Payload

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

Message Send

V1 Message Send Payload

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

V2 Message Send Payload

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

V3 Message Send Payload

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

Number Opt-In

V1 Number Opt-In Payload

Field	Type	Description
originationNumber	string	The number the message was sent from.
destinationNumber	string	The number the message was sent to.
senderName *	string	The sender name used to pre-populate the "To:" field for iMessages.
optInType	enum NumberOptInType	Identifies how the method used to opt-in, see Number Opt-In Types.
type	type: MTAWebhook.NUMBER_OPT_IN	The webhook event type, identifying it as number opt-in.

V2 Number Opt-In Payload

Field	Type	Description
originationNumber	string	The number the message was sent from.
destinationNumber *	string	The number the message was sent to.
senderName *	string	The sender name used to pre-populate the "To:" field for iMessages.
optInType	enum NumberOptInType	Identifies how the method used to opt-in, see Number Opt-In Types.
type	MTAWebhook.NUMBER_OPT_IN	The webhook event type, identifying it as number opt-in.

V3 Number Opt-In Payload

Field	Type	Description
fromNumber	string	The number the message was sent from.
toNumber *	string	The number the message was sent to.
senderName *	string	The sender name used to pre-populate the "To:" field for iMessages.
type	enum NumberOptInType	The webhook event type, identifying it as number opt-in.
timestamp	string | date:UTC:ISO-8601	A date string. The timezone and format are specified.

Number Opt-In Types

One of the fields of the number opt-in webhook is optInType which will return one of the following types, used to indicate the method used to opt-in:

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