How to Set Up Your Webhooks Integration

To start receiving webhook notifications with your endpoint, complete the following steps:

Step 1: Configure your webhook endpoint

At a minimum, your application will need a webhook endpoint URL that meets the following requirements:

  • The endpoint must accept HTTPS POST requests in JSON format when an event occurs.
  • After receiving the data, the endpoint must return a 2xx Success HTTP Status code to confirm the event was successfully received.

Note: TextUs does not provide IP ranges for whitelisting. Our IP addresses can change because our systems utilize a cloud provider. Whitelisting IP ranges in your network firewall for webhooks can cause disruptions in receiving webhook events.

Step 2: Register your webhook endpoint and subscribe to events

When you register your webhook endpoint, you are enabling TextUs to automatically send event objects as a POST request to a URL hosted by your application.

You can register your endpoint with TextUs by using the TextUs web app, or by calling the Integrations API.

Option 1: How to use the TextUs web app to subscribe to events

Note: By default, the TextUs web application can only send two event types: message.delivered and message.received. If you want to subscribe to additional events, you will need to update your settings by calling the Integrations API.

To register and subscribe to events using the integrations API, complete the following steps:

  1. Log in to next.textus.com with your org admin user account.
  2. Click on your user icon and go to Accounts.
  3. On the Accounts page, find your org account at the top of the account hierarchy and click View.
  4. Go to Settings > Account Settings > Integrations.
  5. Under Webhooks, click Add Webhook.
  6. Enter your webhook endpoint URL in the empty field.
  7. Click Save.

Your webhook endpoint is now registered and you can start receiving notifications for message.delivered and message.received. To subscribe to additional events, see the Integrations API documentation.

Option 2: How to use the Integrations API to subscribe to events

The Integrations API allows you to register your endpoint and configure your webhook settings through a single API call:

POST /{your-account-name}/integrations

Path parameters

Path Parameter Type Description
your-account-name String The value for your primary non-messaging account name.

Tip: You can copy the your-account-name value from the address bar of your browser when you are logged in to your primary non-messaging account in the TextUs web app.

For example, an account with the name “PupStar Primary” uses the web address https://next.textus.com/pupstar-primary/contacts/account when accessing the TextUs web app in a browser. To call the Integrations endpoint, the URL would structured as: https://next.textus.com/pupstar-primary/integrations

Request body

When calling the Integrations API, include the following fields in the API request body:

Field Type Description
active Boolean Determines if your integration will push data to your base_url at time of event.
provider String String representing the provider type. Set value to webhook.
config Object Contains your endpoint configuration. See the config object below for more information.
settings Object Contains the actions object.
actions Object Lists the configuration for each webhook event. See the actions object below for more information

The config object

The following table defines parameters that can be included in the config object:

Field Type Description
baseUrl String The URL of the webhook endpoint
webhookSecret String A user-defined token that provides an additional layer of security.
clientSecret String An authentication token for client applications.

The actions object

The following subscription types are supported and can be included in the actions object when calling the Integrations API:

Field Type Description
message.received Boolean Get notified when an incoming message is received.
message.delivered Boolean Get notified when an outgoing message is delivered.
message.failed Boolean Get notified when an outgoing message failed to deliver.
message.unknown Boolean Get notified when an outgoing message could not be delivered due to an unknown error.
phone_call.completed Boolean Get notified when a phone call is completed.
contact.opted_out Boolean Get notified when a contact opted out of receiving text messages.
contact.opted_in Boolean Get notified when a contact opted in to receiving text messages.
contact.created Boolean Get notified when a contact is created.

The example below demonstrates how to call the Integrations API to register an endpoint and enable webhooks for the following events:

  • message.received
  • message.delivered
  • message.failed
  • contact.opted_out
  • contact.opted_in
  • contact.created

Sample API Call 

curl -X POST https://next.textus.com/{your-account-name}/integrations \
  -i -H "Accept: application/vnd.textus+jsonld" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "@type": "Integration",
    "@context": "/contexts/Integration.jsonld",
    "active": true,
    "provider": "webhook",
    "config": {
      "baseUrl": "https://www.example.com/callback"
    },
    "settings": {
      "actions": {
        "message.received": true,
        "message.delivered": true,
        "message.failed": true,
        "message.unknown": false,
        "phone_call.completed": false,
        "contact.opted_out": true,
        "contact.opted_in": true,
        "contact.created": true
      }
    }
  }'

Step 3: Webhook endpoint best practices

After you confirm that your webhook endpoint connection works as expected, we recommend you secure the connection by following our webhook best practices listed in the sections below.

Signature verification

Webhook payloads include a cryptographic signature in the X-TextUs-Signature header, which you can optionally use to verify that the message is legitimate.

To verify a webhook payload with the cryptographic signature, complete the following steps:

  1. Get the signature from the header.
  2. Prepare the signed payload, which is the request body.
  3. Determine the expected signature value by calculating an HMAC using SHA256. Use your webhook’s secret as the key and the request body as the message.
  4. Compare your calculated signature with the one in the X-TextUs-Signature field. If the values match, the request is authentic.

The following example demonstrates how to build logic that verifies a payload’s signature using Ruby programming language:

secret_key = "textus-HOTh4kXxHIbYst0xutpkdw"       # From the Webhook config
payload    = request.body                          # The incoming webhook request
signature  = request.headers["X-TextUs-Signature"]

digest = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), secret_key, payload)

if digest == signature
  # handle webhook
else
  error "Webhook request did not come from TextUs!"
end

Error handling

If your endpoint responds to a webhook event with anything other than a Success (2xx) HTTP status, we categorize this as a failure in one of the following ways:

  • Transient Errors: If the endpoint responds with a 504 Gateway Timeout status code, we assume the server is busy, and we will periodically retry delivering the event with an exponential backoff for up to 12 hours.

    If your endpoint received the event but was slow in responding to the webhook request, we may assume the event failed and retry sending it, potentially causing duplicate events to be processed by your application. To avoid this for message events, we provide an identification field that you can use to check if the message event has already been processed.

  • Fatal Errors: If any error status in the 4xx or 5xx range occurs, your webhook integration will be marked as “failed” in our system. We’ll pause sending events to your endpoint and save them in our system. We’ll continue to make hourly attempts to resend the events and look for a successful response from your endpoint. If your endpoint returns a 2xx (Success) HTTP status, we’ll clear the “failed” status from your integration and replay the pending events. If your endpoint keeps returning errors, we’ll keep trying every hour until the event succeeds or until you update your integration settings.

Handling asynchronous webhook events

In situations where you have a high volume of webhook events to process, handling webhooks asynchronously protects your system and allows your webhook integration to process events without errors.

Currently, TextUs does not throttle events sent to your webhook endpoint. This means that if your TextUs account generates a lot of event traffic, especially for message events, your webhook endpoint may struggle to scale and process all events without errors.

To handle asynchronous webhook events, we recommend implementing a message queue system to efficiently manage and process webhook notifications.

Step 4: Manage your integration and event subscriptions

You can update or delete existing webhook endpoints, and manage your event subscriptions using the Integrations API. For more information, see the Integrations API documentation.

© 2024 TextUs