Setting up Webhooks

Learn how to set up webhooks with the Mobile Text Alerts API

With Mobile Text Alerts webhooks you can receive real time notifications of events, such as: sent messages, message replies, and delivery statuses. With the Mobile Text Alerts API you can register, delete, and view the webhooks on your account.

Webhooks Overview

Webhooks are a way for applications to communicate with each other, with real-time data sent from one application to another whenever a given event occurs. For events you want to be notified of, you can configure a webhook to your specified URL.

For example, when a user replies to a message that was sent; MTA receives the inbound message from a provider and will post the inbound message to your provided endpoint.

Event Types

The Mobile Text Alerts API supports the following event types for webhooks:

Message Reply message-reply

When MTA receives an an inbound message from a provider, MTA will post the inbound message to the customer provided endpoint.

View Message Reply payload

Delivery Status delivery-status

When MTA receives an updated delivery status from a provider regarding a customer's sent message.

View Delivery Status payload

Message Send message-send

When MTA send a message to a provider, MTA will post the message to the customer provided endpoint.

View Message Send payload

Number Opt-In number-opt-in

You must receive an inbound opt-in message before you send outbound iMessages and RCS messages. This webhook will post the opt-in event to the customer provided endpoint.

View Number Opt-In payload

Webhook Failure Email Alerts

When registering a webhook, you can choose to receive emails if MTA fails to send a request to your configured URL or a non-200 response code was received. To receive these email alerts: when registering a webhook, set sendAlertEmail to true , with alertEmail set to the intended email address.

Register a Webhook

POST /webhooks

Webhooks can be created for your account by calling the Register Webhooks /webhooks endpoint of the MTA API.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <APIKey>

Request Fields

Name	Type	Description
event(required)	string	The event type to be registered: message-reply, delivery-status,message-send , or number-opt-in.
url(required)	string	This is your hosted URL endpoint that MTA will make a POST request to when events trigger. The only requirement for this endpoint is that the response has a 200 HTTP status code.
secret(required)	string	This is shared secret between your organization and MTA, used to authenticate webhook requests. Your webhook listener validates the value in the request with the shared secret.
alertEmail	string	The email address to be contacted for failure email alerts. If an alertEmail is not configured but sendAlertEmail is set to true, the account's main email will be used.
sendAlertEmail	boolean	Default value is false . If true, MTA will send a failure alert email to the configured alertEmail on the webhook. Iffalse (or not supplied when registering the webhook) no failure email alerts will be sent.
skipErrors	boolean	If set to true, all error responses(non-200) for requests to your configured URL will be ignored. If failure email alerts are configured, they will not be triggered.
skipErrorCodes	string[]	This field can be used to indicate specific error codes to be ignored, failure email alerts will not be sent for these codes.
retryOnError	boolean	If set to true, a retry request will be made to your configured URL if the previous request resulted in an error response. Which responses are errors is determined by if skipErrors is enabled (all non-200 status codes ignored as errors) or skipErrorCodes (all specified error codes ignored as errors). MTA uses exponential backoff for retry calls, with up to 2 retry attempts.
maxThroughputPerMinute	number	Indicate the maximum number of requests that can be sent to the configured URL in a 60 second window.

Response

200

{
  "message": "Webhook 11 created successfully.",
  "data": {
    "id": 11,
    "event": "delivery-status",
    "url": "https://www.example.com/app/hooks",
    "alertEmail": "[e-mail]",
    "sendAlertEmail": true,
    "skipErrors": false,
    "skipErrorCodes": [],
    "retryOnError": true,
    "maxThroughputPerMinute": 600,
    "createdAt": "2022-04-18T05:00:00.000Z"
  }
}

400

{
  "error": "Invalid request"
}

Learn more

See the expected event payloads for MTA webhooks:

Webhooks Event Payloads

Just getting started with webhooks?

Setting up your first webhook