Receiving Webhooks

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

Telnyx supports notifications for the following event types:

Each event notification also includes a [Telnyx signature] , which allows you to check that it was sent by Telnyx and not a third-party.

Hierarchy of URLs

Telnyx first tries the primary URL on your Messaging Profile. If that URL does not resolve, or your application returns a response other than an "200 OK", the webhook will be delivered to the failover URL, if one has been specified.

Delivery Status Updates

Delivery status webhooks are configured on a per [outbound message request] basis, using the delivery_status_[webhook|failover]_url field. When configured, the Telnyx Messaging Services will attempt to notify you about each status update. The current [MDR] is included as the request payload.

Incoming Messages

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

sms_id Unique identifier for the message request (UUID represented as a string).
from Sender's +E.164 formatted phone number.
to Receiver's +E.164 formatted phone number.
body Content of the message as a non-empty string. MMS messages will include the subject and all text/plain attachments, concatenated with newlines (\n).
media MMS messages will contain an array with zero or more elements, one for each attached media file (other than text/plain).
media.#.url A publicly accessible URL hosting the media. After 30 days, the media will be deleted.
media.#.content_type The MIME content type of the media.
media.#.hash_sha256 The SHA-256 hex digest of the media.
media.#.size Size of the media in bytes.

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.

Telnyx Webhook Signature

Each messaging webhook event that we send you will include a Telnyx signature. The signature allows you to validate that webhooks were not sent by a third-party.

To mitigate the possibility of an attacker intercepting a valid payload and its signature, and then re-transmitting them, Telnyx includes a timestamp in the Telnyx-Signature header. As this timestamp is part of the signed payload, it is also verified by the signature. An attacker cannot change the timestamp without invalidating the signature. In cases where the signature is valid but the timestamp is too old, the payload can be rejected.

Signature Generation

Note: This process is illustrated in the [inbound message example] .

Our signature is generated as follows:

  1. Build the hash function's input by concatenating together the following, in order:
timestamp Unix time in seconds [10-digit] ASCII encoded string
period`(.)` One full stop character (U+002E) ASCII encoded string
payload Raw request payload bytes UTF-8 encoded (JSON) string
  1. Then an HMAC with the SHA256 hash function is used, using the endpoint’s signing secret as the key and the concatenated data above as the message.
  2. The resultant hash is then base64 encoded , providing the signature.

Signature Header

  1. The timestamp and signature are included as an HTTP request header . The X-Telnyx-Signature header contains the following comma-separated information:
  2. t= followed by the timestamp
  3. h= prepended to a signature
Copy
Copied
X-Telnyx-Signature: t=1520983646,h=WlEXoEsHH2RMgy2x8eyvg10JlMBco0s51fdNpMORF00=

Note: After pasting the above content, Kindly check and remove any new line added

Telnyx Webhook IPs

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

192.76.120.192/27