Setting up your first webhook

Learn how to set up a webhook endpoint on your server which will listen to events sent from Mobile Text Alerts

1

Create your webhook endpoint

You will need to create an endpoint on your server to receive event notifications. Mobile Text Alerts will send HTTP POST requests to this endpoint and expects it to return a response with a 200 HTTP status code. If other status codes are returned, this is treated as a failed request. You can configure email alerts when Mobile Text Alerts receives these failed requests when registering your webhook.

Use a secure endpoint (HTTPS not HTTP). This eliminates risks by encrypting the entire request while in transit.

Once configured and registered, this endpoint will receive event payloads from Mobile Text Alerts. Request bodies are JSON. You can view the expected event payloads for each event type here.

2

Get the URL of this endpoint

Mobile Text Alerts 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 Register Webhook endpoint for each event type you want to receive, each with the same url field.

Example URL:

https://www.yoursite.com/app/hooks

3

Create a secret value

When registering a webhook, you are required to provide a secret value to Mobile Text Alerts. This is typically a 128-character hexadecimal string. This is used to validate that the requests you receive are from Mobile Text Alerts.

Secret Best Practices:

• Store your secret as an environment variable or in a secrets manager (e.g. AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager).

• Never commit the secret to source control.

• Never log the secret or include it in error responses.

Example secret generation:

Unix / macOS

openssl rand -hex 64

Python

python3 -c "import secrets; print(secrets.token_hex(64))"

Node.js

node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

Mobile Text Alerts will generate a HMAC-SHA256 signature using the request body and the secret. The signature is set as an X-Signature header in the request Mobile Text Alerts sends to your endpoint.

Your webhook listener should validate that the request is from Mobile Text Alerts by generating the HMAC-SHA256 signature of the request body and comparing it to the value of the X-Signature header.

Mobile Text Alerts provides the X-Signature header signature as a robust validation mechanism for your security but does not enforce verification of your endpoint listener. This makes client-side enforcement a developer responsibility. See Webhook Signature Verification to learn more.

4

Register your webhook

You will need to register your webhook endpoint for each event type you want to receive. To do this, call the Register Webhook /webhooks endpoint of the Mobile Text Alerts API.

Required fields:

• event: string - Choose which event type you want to receive 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 Mobile Text Alerts will make a POST request to when events trigger.

• secret: string - This is a shared secret between your organization and Mobile Text Alerts (created in step 3 above).

Click here to see all fields.

Example request:

cURL

curl --location '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": "[e-mail]",
    "sendAlertEmail": true
}'

Node.js

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: '[e-mail]',
      sendAlertEmail: true
    })
  });

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

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

Python

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': '[e-mail]',
        'sendAlertEmail': True
    }
    )
print(response.json())

Example successful 200 response:

(Note: The response contains the id field which is the webhookId used in requests to update/delete this webhook.)

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

5

Receive event payloads to your URL

Once your webhook is registered, you will start receiving the event payloads when that event is triggered.

Your server can parse this JSON and use this payload data however you configure your server.

For production environments your listener server should always verify signatures of requests to confirm they are from Mobile Text Alerts.

Your webhook configuration can be updated or deleted after registration by calling the Update Webhook endpoint or Delete Webhook endpoint. For these requests use the {webhookId} returned when you first registered the webhook.