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.
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 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.
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
||Unique identifier for the message request (UUID represented as a string).|
||Sender's +E.164 formatted phone number.|
||Receiver's +E.164 formatted phone number.|
Content of the message as a non-empty string. MMS messages will include the subject and all
MMS messages will contain an array with zero or more elements, one for each attached media file (other than
||A publicly accessible URL hosting the media. After 30 days, the media will be deleted.|
||The MIME content type of the media.|
||The SHA-256 hex digest of the media.|
||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.
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.
Note: This process is illustrated in the inbound message example.
Our signature is generated as follows:
- 1Build 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
- 2Then 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.
- 3The resultant hash is then base64 encoded, providing the signature.
- 4The timestamp and signature are included as an HTTP request header. The
X-Telnyx-Signatureheader contains the following comma-separated information:
t=followed by the timestamp
h=prepended to a signature
If you use an ACL or Firewall on your network, make sure you whitelist the following subnet(s):