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.

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.

Mobile Text Alerts will generate a SHA-256 HMAC 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 SHA-256 HMAC signature of the request body and comparing it to the value of the X-Signature header.

Mobile Text Alerts provides this signature as a robust validation mechanism for your security. This validation process is not mandatory or enforced by Mobile Text Alerts. You can still receive and act on webhook callbacks without signature verification.

This is a common security best practice. It helps ensure your webhook endpoints are secure and handle only valid requests from Mobile Text Alerts. But you can choose if and how you implement validation.

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 --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
}'

Example successful 200 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"
  }
}

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.

Your webhook configuration can be updated after registration by calling the Update Webhook endpoint: PATCH https://api.mobile-text-alerts.com/{VERSION}/webhooks/{webhookId}. Use the {webhookId} returned when you first registered the webhook.