Webhooks

For more information on how to use these endpoints see Setting up Webhooks and Webhooks.

Register Webhook POST /webhooks
List Webhooks GET /webhooks
Update Webhook PATCH /webhooks/{webhookId}
Delete Webhook DELETE /webhooks/{webhookId}

You will need the {webhookId} of the webhook you want to update/delete. The ids for all your registered webhooks can be found by calling the List Webhooks endpoint.

Register Webhook

POST /webhooks

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 Mobile Text Alerts 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 Mobile Text Alerts, 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, Mobile Text Alerts 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).

Mobile Text Alerts 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.

Example Request

curl --location --request POST 'https://api.mobile-text-alerts.com/v3/webhooks' \
  --header 'Authorization: Bearer <APIKey>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "event": "delivery-status",
    "url": "https://www.example.com/app/hooks",
    "secret": "abc123-abc2-cde1-1234-xyz123456",
    "alertEmail": "[email protected]",
    "sendAlertEmail": true
}'

Requirements: Node.js 18+ (native fetch) and an MTA_API_KEY environment variable.

async function main() {
  const response = await fetch('https://api.mobile-text-alerts.com/v3/webhooks', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.MTA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      event: 'delivery-status',
      url: 'https://www.example.com/app/hooks',
      secret: 'abc123-abc2-cde1-1234-xyz123456',
      alertEmail: '[email protected]',
      sendAlertEmail: true
    })
  });

  const data = await response.json();
  console.log(data);
}

main().catch((err) => {
  console.error('Request failed:', err);
  process.exitCode = 1;
});

Requirements: pip install requests and an MTA_API_KEY environment variable.

import requests
import os

response = requests.post(
    'https://api.mobile-text-alerts.com/v3/webhooks',
    headers={
        'Authorization': f'Bearer {os.getenv("MTA_API_KEY")}',
        'Content-Type': 'application/json'
    },
    json={
        'event': 'delivery-status',
        'url': 'https://www.example.com/app/hooks',
        'secret': 'abc123-abc2-cde1-1234-xyz123456',
        'alertEmail': '[email protected]',
        'sendAlertEmail': True
    }
    )
print(response.json())

Response

{
  "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"
  }
}

{
  "httpCode": 400,
  "message": "text",
  "timestamp": "2026-02-10T03:37:28.425Z",
  "type": "bad_request_error",
  "name": "MTABadRequestError",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

{
  "httpCode": 401,
  "message": "text",
  "timestamp": "2026-02-10T03:37:28.425Z",
  "type": "unauthorized_error",
  "name": "MTAUnauthorizedError",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

{
  "httpCode": 403,
  "message": "text",
  "timestamp": "2026-02-10T03:37:28.425Z",
  "type": "forbidden_error",
  "name": "MTAForbiddenError",
  "requestId": "123e4567-e89b-12d3-a456-426614174000",
  "reason": null
}

{
  "httpCode": 500,
  "message": "text",
  "timestamp": "2026-02-10T03:37:28.425Z",
  "type": "internal_server_error",
  "name": "MTAInternalServerError",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

List Webhooks

GET /webhooks

You can view all the webhooks that have been configured for your account by calling the List Webhooks endpoint.

Headers

Name

Value

Content-Type

application/json

Authorization

Bearer <APIKey>

Example Request

curl -L \
  -H 'Authorization: Bearer <APIKEY>' \
  'https://api.mobile-text-alerts.com/v3/webhooks'

Response

{
  "data": {
    "rows": [
      {
        "id": 100,
        "event": "delivery-status",
        "url": "https://example.com/webhook/delivery",
        "alertEmail": "[email protected]",
        "createdAt": "2021-01-01T00:00:00.000Z"
      },
      {
        "id": 101,
        "event": "message-reply",
        "url": "https://example.com/webhook/reply",
        "alertEmail": "[email protected]",
        "createdAt": "2021-01-01T00:00:00.000Z"
      }
    ],
    "page": 0,
    "pageSize": 25,
    "total": 2
  }
}

{
  "httpCode": 400,
  "message": "text",
  "timestamp": "2026-02-10T03:37:28.425Z",
  "type": "bad_request_error",
  "name": "MTABadRequestError",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

{
  "httpCode": 401,
  "message": "text",
  "timestamp": "2026-02-10T03:37:28.425Z",
  "type": "unauthorized_error",
  "name": "MTAUnauthorizedError",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

{
  "httpCode": 403,
  "message": "text",
  "timestamp": "2026-02-10T03:37:28.425Z",
  "type": "forbidden_error",
  "name": "MTAForbiddenError",
  "requestId": "123e4567-e89b-12d3-a456-426614174000",
  "reason": null
}

{
  "httpCode": 500,
  "message": "text",
  "timestamp": "2026-02-10T03:37:28.425Z",
  "type": "internal_server_error",
  "name": "MTAInternalServerError",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Update Webhook

PATCH /webhooks/{webhookId}

You can edit an existing webhook you have created on your account by calling this endpoint. The path includes the {webhookId} of the webhook to be updated.

Headers

Name

Value

Content-Type

application/json

Authorization

Bearer <APIKey>

Request Fields

event: string - Event type. One of: message-reply, delivery-status, message-send, number-opt-in.
url: string - Your hosted endpoint URL that receives webhook POST requests.
secret: string - Shared secret used to sign webhook requests.
alertEmail: string - Email address to receive failure alerts.
sendAlertEmail: boolean - If true, send failure alert emails.
skipErrors: boolean - If true, ignore all non-200 responses from your endpoint.
skipErrorCodes: string[] - Error codes to ignore.
retryOnError: boolean - If true, retry failed webhook requests (exponential backoff, up to 2 attempts).
maxThroughputPerMinute: number - Max requests per 60-second window.

Example Request

curl -L \
  --request PATCH \
  --url 'https://api.mobile-text-alerts.com/v3/webhooks/11' \
  --header 'Authorization: Bearer <APIKey>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "url": "https://www.example.com/app/hooks",
    "secret": "abc123-abc2-cde1-1234-xyz123456",
    "alertEmail": "[email protected]",
    "sendAlertEmail": true,
    "maxThroughputPerMinute": 1000
}'

Requirements: Node.js 18+ (native fetch) and an MTA_API_KEY environment variable.

async function main() {
  const response = await fetch('https://api.mobile-text-alerts.com/v3/webhooks/11', {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${process.env.MTA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: 'https://www.example.com/app/hooks',
      secret: 'abc123-abc2-cde1-1234-xyz123456',
      alertEmail: '[email protected]',
      sendAlertEmail: true,
      maxThroughputPerMinute: 1000
    })
  });

  const data = await response.json();
  console.log(data);
}

main().catch((err) => {
  console.error('Request failed:', err);
  process.exitCode = 1;
});

Requirements: pip install requests and an MTA_API_KEY environment variable.

import requests
import os

response = requests.patch(
    'https://api.mobile-text-alerts.com/v3/webhooks/11',
    headers={
        'Authorization': f'Bearer {os.getenv("MTA_API_KEY")}',
        'Content-Type': 'application/json'
    },
    json={
        'url': 'https://www.example.com/app/hooks',
        'secret': 'abc123-abc2-cde1-1234-xyz123456',
        'alertEmail': '[email protected]',
        'sendAlertEmail': True,
        'maxThroughputPerMinute': 1000
    }
    )
print(response.json())

Response

{
  "message": "Webhook 11 updated 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": 1000,
    "createdAt": "2022-04-18T05:00:00.000Z"
  }
}

{
  "httpCode": 400,
  "message": "text",
  "timestamp": "2026-02-10T03:37:28.425Z",
  "type": "bad_request_error",
  "name": "MTABadRequestError",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

{
  "httpCode": 401,
  "message": "text",
  "timestamp": "2026-02-10T03:37:28.425Z",
  "type": "unauthorized_error",
  "name": "MTAUnauthorizedError",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

{
  "httpCode": 403,
  "message": "text",
  "timestamp": "2026-02-10T03:37:28.425Z",
  "type": "forbidden_error",
  "name": "MTAForbiddenError",
  "requestId": "123e4567-e89b-12d3-a456-426614174000",
  "reason": null
}

{
  "httpCode": 500,
  "message": "text",
  "timestamp": "2026-02-10T03:37:28.425Z",
  "type": "internal_server_error",
  "name": "MTAInternalServerError",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Delete Webhook

DELETE /webhooks/{webhookId}

Webhooks can be deleted without needing to supply a request body. Simply include the {webhookId} of the webhook to be deleted as a path parameter.

Headers

Name

Value

Content-Type

application/json

Authorization

Bearer <APIKey>

Example Request

curl -L \
  --request DELETE \
  --url 'https://api.mobile-text-alerts.com/v3/webhooks/11' \
  --header 'Authorization: Bearer <APIKey>'

const response = await fetch('https://api.mobile-text-alerts.com/v3/webhooks/11', {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${process.env.MTA_API_KEY}`
  }
});

const data = await response.json();
console.log(data);

import requests
import os

response = requests.delete(
    'https://api.mobile-text-alerts.com/v3/webhooks/11',
    headers={'Authorization': f'Bearer {os.getenv("MTA_API_KEY")}'}
)

print(response.json())

Response

{
  "message": "Webhook 11 deleted successfully."
}

{
  "httpCode": 400,
  "message": "text",
  "timestamp": "2026-02-10T03:37:28.425Z",
  "type": "bad_request_error",
  "name": "MTABadRequestError",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

{
  "httpCode": 401,
  "message": "text",
  "timestamp": "2026-02-10T03:37:28.425Z",
  "type": "unauthorized_error",
  "name": "MTAUnauthorizedError",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

{
  "httpCode": 403,
  "message": "text",
  "timestamp": "2026-02-10T03:37:28.425Z",
  "type": "forbidden_error",
  "name": "MTAForbiddenError",
  "requestId": "123e4567-e89b-12d3-a456-426614174000",
  "reason": null
}

{
  "httpCode": 500,
  "message": "text",
  "timestamp": "2026-02-10T03:37:28.425Z",
  "type": "internal_server_error",
  "name": "MTAInternalServerError",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

PreviousVerify NextWebinars

Last updated 26 minutes ago

Was this helpful?

hashtagRegister Webhook

hashtagList Webhooks

hashtagUpdate Webhook

hashtagDelete Webhook

Register Webhook

List Webhooks

Update Webhook

Delete Webhook