Setting up your first webhook

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

1

Create your webhook endpoint

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 email alerts when MTA receives these failed requests 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 expected event payloads for each event type here.

2

Get the URL of this endpoint

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 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 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 SHA-256 HMAC signature using the request body and the secret . This is set as a X-Signature header in the request MTA sends to your endpoint.

Your 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.

Mobile Text Alerts provides this signature as a robust validation mechanism for your security. This validation process is not mandatory or enforced by MTA, you are able to receive and act upon webhook callbacks without this signature verification.

This is a common security best practice to ensure your webhook endpoints are as secure and only handle valid requests from MTA. But you as the developer can choose how/if you will 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 you will call the Register Webhook /webhooks endpoint of the MTA API.

Required fields:

• 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).

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": "[e-mail]",
    "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": "[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.

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