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.
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
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:
One of the fields of the delivery status webhook is status which will return a code that is associated with the following statuses:
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:
date - A date string. The timezone and format are specified.
string
The id provided by the customer when the message was sent.
status
MTADeliveryStatus
The delivery status. See .
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.
string
The id provided by the customer when the message was sent.
status
MTADeliveryStatus
The delivery status. See .
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.
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 .
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.
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.
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.
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.
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.
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.
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.
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 .
type
type: MTAWebhook.NUMBER_OPT_IN
The webhook event type, identifying it as number opt-in.
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 .
type
MTAWebhook.NUMBER_OPT_IN
The webhook event type, identifying it as number opt-in.
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.
destinationNumber
string
The number the message was sent to.
messageId
number
The MTA internal id of the outbound message.
destinationNumber
string
The number the message was sent to.
messageId
number
The MTA internal id of the outbound message.
fromNumber *
string |phone_e164
The number that the message was sent from.
toNumber
string |phone_e164
The number the message was sent to.
originationNumber
string
The number that the inbound message was sent from.
destinationNumber
number
The number that the inbound message was sent to.
originationNumber
string
The number that the inbound message was sent from.
destinationNumber
string
The number that the inbound message was sent to.
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.
destinationNumber
string
The number the message was sent to.
messageId
string | number
The MTA internal id of the outbound message.
destinationNumber
string
The number the message was sent to.
messageId
number
The MTA internal id of the outbound message.
fromNumber *
string |phone_e164
The number that the message was sent from.
toNumber
string |phone_e164
The number the message was sent to.
originationNumber
string
The number the message was sent from.
destinationNumber
string
The number the message was sent to.
originationNumber
string
The number the message was sent from.
destinationNumber *
string
The number the message was sent to.
fromNumber
string
The number the message was sent from.
toNumber *
string
The number the message was sent to.
externalId
externalId
messageId
message
message
replyId
externalId
externalId
messageId
senderName *
senderName *
senderName *
"tags": {
"key": "value"
}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 messageenum NumberOptInType {
SMS = 'sms',
EMAIL = 'email',
IMessage = 'imessage',
RCS = 'rcs',
}Learn how to set up a webhook endpoint on your server which will listen to events sent from MTA
You will need to create an endpoint on your server to receive the event notifications. MTA will send HTTP POST requests to this endpoint and will expect it to return a response with a 200 HTTP status code. If other status codes are returned, this will be treated as a failed request. You can configure when registering your webhook.
Once configured and registered, this endpoint will receive the event payloads from MTA. The body of the requests are JSON; you can view the .
MTA will send HTTP POST requests to the URL of your server endpoint.
A url must be specified for each webhook event type that you register. You can configure multiple event types to be sent to the same destination URL endpoint. This would require multiple calls to the endpoint for each event type you want to receive, each with the same url
When registering a webhook you are required to provide a secret value to MTA. This is typically 128 character hexadecimal string. This is used for security to validate that the requests you receive are from MTA.
MTA will generate a signature using the request body and the secret . This is set as a
Once your webhook is registered, you will start receiving the when that event is triggered. Your server can parse this JSON and use this payload data however you configure your server.
Your webhook configuration can be updated after registration by calling Update Webhook endpoint PATCH https://api.mobile-text-alerts.com/{VERSION}/webhooks/{webhookId}
Example URL:
X-SignatureYour webhook listener should validate the request is from MTA by generating the SHA-256 HMAC signature of the request body and comparing it to the value of the X-Signature header.
event: string - Choose which event type you want to receive the event notifications for. This can be one of the following: message-reply, delivery-status,message-send , or number-opt-in.
url: string - This is your hosted URL endpoint (created in step 2 above) that MTA will make a POST request to when events trigger.
secret: string - This is shared secret between your organization and MTA (created in step 3 above).
Example request:
Example successful 200 response:
{webhookId}https://www.yoursite.com/app/hookscurl --location 'https://api.mobile-text-alerts.com/v3/webhooks' \
--header 'Authorization: Bearer 89fa747a-e01b-5940-99c2-4e96fa996258' \
--data-raw '{
"event": "delivery-status",
"url": "https://www.example.com/app/hooks",
"secret": "abc123-abc2-cde1-1234-xyz123456",
"alertEmail": "[email protected]",
"sendAlertEmail": true
}'{
"message": "Webhook 11 created successfully.",
"data": {
"id": 11,
"event": "delivery-status",
"url": "https://www.example.com/app/hooks",
"alertEmail": "[email protected]",
"sendAlertEmail": true,
"skipErrors": false,
"skipErrorCodes": [],
"retryOnError": true,
"maxThroughputPerMinute": 600,
"createdAt": "2022-04-18T05:00:00.000Z"
}
}