Description

A webhook (also called a web callback or HTTP push API) is a way for an app to provide other applications with real-time information. A webhook delivers data to other applications as it happens, meaning you get data immediately.

You can choose to be notified about events that Telnyx sends to you on your SMS-capable long code or toll-free phone number by configuring webhooks.

Telnyx supports notifications for the following event types:

Whitelist

If you use an ACL or Firewall on your network, make sure you whitelist the following subnet(s): 192.76.120.192/27

CIDR IP Range 192.76.120.192 - 192.76.120.223

192.76.120.192

192.76.120.193

192.76.120.194

192.76.120.195

192.76.120.196

192.76.120.197

192.76.120.198

192.76.120.199

192.76.120.200

192.76.120.201

192.76.120.202

192.76.120.203

192.76.120.204

192.76.120.205

192.76.120.206

192.76.120.207

192.76.120.208

192.76.120.209

192.76.120.210

192.76.120.211

192.76.120.212

192.76.120.213

192.76.120.214

192.76.120.215

192.76.120.216

192.76.120.217

192.76.120.218

192.76.120.219

192.76.120.220

192.76.120.221

192.76.120.222

192.76.120.223

Requirements

For this mechanism to work, you’ll need a publicly accessible HTTP server that can receive our webhook requests at one or more specified URLs. We highly recommend using HTTPS (instead of HTTP).

This tutorial walks through setting up a basic application for receiving webhooks.

Hierarchy of URLs

If webhooks are provided in the request body, we will use those, otherwise if the profile has webhooks, we’ll use those. If neither has webhooks, we won’t attempt a webhook delivery.

Delivery Status Updates

The Telnyx Messaging Services will attempt to notify you about each status update based on the hierarchy of URLs above.

Delivery Status Payload

Here is an example of a webhook event where a delivery receipt is returned to the sender after sending a message through a Telnyx long code to a T-Mobile long code:

{
"data":{
"event_type":"message.finalized",
"id":"4ee8c3a6-4995-4309-a3c6-38e3db9ea4be",
"occurred_at":"2019-12-09T21:32:14.148+00:00",
"payload":{
"completed_at":"2019-12-09T21:32:14.148+00:00",
"cost":null,
"direction":"outbound",
"encoding":"GSM-7",
"errors":[
],
"from":{
"carrier":"T-Mobile USA",
"line_type":"Wireless",
"phone_number":"+13125000000",
"status":"webhook_delivered"
},
"id":"ac012cbf-5e09-46af-a69a-7c0e2d90993c",
"media":[
],
"messaging_profile_id":"83d2343b-553f-4c5f-b8c8-fd27004f94bf",
"organization_id":"9d76d591-1b7d-405d-8c64-1320ee070245",
"parts":1,
"received_at":"2019-12-09T21:32:13.552+00:00",
"record_type":"message",
"sent_at":"2019-12-09T21:32:13.596+00:00",
"tags":[
],
"text":"Hello there!",
"to":[
{
"carrier":"T-MOBILE USA, INC.",
"line_type":"Wireless",
"phone_number":"+13125000000",
"status":"delivered"
}
],
"type":"SMS",
"valid_until":"2019-12-09T22:32:13.552+00:00",
"webhook_failover_url":"",
"webhook_url":"http://webhook.site/af3a92e7-e150-442c-9fe6-61658ce26b1a"
},
"record_type":"event"
},
"meta":{
"attempt":1,
"delivered_to":"http://webhook.site/af3a92e7-e150-442c-9fe6-61658ce26b1a"
}
}

Delivery Statuses

Delivery Status Payload

Telnyx gives you the option of using webhooks to notify you of new inbound messages to your SMS-capable long code and toll-free phone numbers. This feature is enabled by configuring the incoming webhooks on the associated messaging profile

Note: Regardless of whether you have configured webhook delivery, records of your received messages are still available in your reports, accessible in the Mission Control Portal or using the Reports API endpoint.

Incoming Message Payload

Here is an example of a webhook event where a Telnyx Long Code receives a text message from a T-Mobile long code:

{
"data":{
"event_type":"message.received",
"id":"b301ed3f-1490-491f-995f-6e64e69674d4",
"occurred_at":"2019-12-09T20:16:07.588+00:00",
"payload":{
"completed_at":null,
"cost":null,
"direction":"inbound",
"encoding":"GSM-7",
"errors":[
],
"from":{
"carrier":"T-Mobile USA",
"line_type":"long_code",
"phone_number":"+1312500000",
"status":"webhook_delivered"
},
"id":"84cca175-9755-4859-b67f-4730d7f58aa3",
"media":[
],
"messaging_profile_id":"740572b6-099c-44a1-89b9-6c92163bc68d",
"organization_id":"47a530f8-4362-4526-829b-bcee17fd9f7a",
"parts":1,
"received_at":"2019-12-09T20:16:07.503+00:00",
"record_type":"message",
"sent_at":null,
"tags":[
],
"text":"Hello from Telnyx!",
"to":[
{
"carrier":"Telnyx",
"line_type":"Wireless",
"phone_number":"+1773005000",
"status":"webhook_delivered"
}
],
"type":"SMS",
"valid_until":null,
"webhook_failover_url":null,
"webhook_url":"http://webhook.site/04bbd2e3-09b5-4c9e-95de-a1debeb9e675"
},
"record_type":"event"
},
"meta":{
"attempt":1,
"delivered_to":"http://webhook.site/04bbd2e3-09b5-4c9e-95de-a1debeb9e675"
}
}


Note: MMS media links will be available for 30 days after message receipt. After 30 days the link will expire and the media will no longer be available through Telnyx.

Responding to a webhook

To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code. Any other information returned in the request headers or request body is ignored. All response codes outside this range, including 3xx codes, will indicate to Telnyx that you did not receive the webhook. URL redirection or a "Not Modified" response will be treated as a failure.

Retries

Webhooks will be retried to each of the supplied URLs if your application does not respond in 2000 milliseconds.

Best Practices

If your webhook script performs complex logic or makes network calls, it's possible the script would timeout before Telnyx sees its complete execution. For that reason, you may want to have your webhook endpoint immediately acknowledge receipt by returning a 2xx HTTP status code, and then perform the rest of its duties.

Webhook endpoints may occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the events you've processed, and then not processing already-logged events. Additionally, we recommend verifying webhook signatures to confirm that received events are being sent from Telnyx.

Best Practices

Telnyx signs the webhook events it sends to clients so that the authenticity of the request can be verified. Webhook signing in API V2 uses public key encryption. Telnyx stores a public-private key pair and uses the private key to sign the payload.

The public key is available to you so that you can verify the request.

The public key can be viewed in the Mission Control Portal

The signature for the payload is calculated by building a string that is the combination of the timestamp of when the request was initiated, the pipe | character and the JSON payload. The signature is then Base64 encoded.

Base64.encode64("#{timestamp}|#{payload}")

The signature (Base64 encoded) and the timestamp (in Unix format) are assigned to the request headers telnyx-signature-ed25519 and telnyx-timestamp respectively.

You can then use cryptographic libraries in your language of choice to verify the signature using the public key. For examples, please see:

Can't find what you're looking for? Click the chat bubble at your lower right-hand corner and talk to the support team!

Did this answer your question?