telnyx 5.38.0 → 5.38.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da4cb6122eefdc8ddf57152d47edd56e0983f3d228b2db64f57f3c33cf1daa43
-  data.tar.gz: 2258bab28da996a1a223c9bab28705e5260c968383652821bc2d719cfb6f67d5
+  metadata.gz: 18f02735965f6afbffaec63905bdc5d5b951c5cac8a5eb4ec550c1777933d485
+  data.tar.gz: 23493c86e9635ca193f9b0b6aac0b97c5003907bcc559108bdc0f544529516e7
 SHA512:
-  metadata.gz: f778d0c0d0d01ef041ddbcb287603507eb1e3d6618f89c006c1e5365d5a88bc6c5d827b0449bfae14b2e6bea0fc190147a7a609ba915a1cd0501a510e31ac1cc
-  data.tar.gz: 60099f06f8bb50305fd0944057541436883567011c0a8fbe0900ec82a95338b7120d415dc910d64bf754504b58cb795426b520ebba998641e33a2fdb5460f25c
+  metadata.gz: 7d456f5bc0c2a1cbc4a15cb6b434234894539c6e3327d15b35159decc0797d752b4381147521714d9031dd4b2941618fc03c7b079eb8ad4270b05381747c5721
+  data.tar.gz: 9a85318ee403c82111ced92fdcc0dee90a4ee266c9b657b52ed7b7270405408d06b5f74438861bedd29c47c76d0c099efb277434c02ebeb369ba52ad8d77fc73

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 5.38.1 (2026-02-24)
+
+Full Changelog: [v5.38.0...v5.38.1](https://github.com/team-telnyx/telnyx-ruby/compare/v5.38.0...v5.38.1)
+
 ## 5.38.0 (2026-02-24)
 
 Full Changelog: [v5.37.0...v5.38.0](https://github.com/team-telnyx/telnyx-ruby/compare/v5.37.0...v5.38.0)

data/README.md

@@ -24,7 +24,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "telnyx", "~> 5.38.0"
+gem "telnyx", "~> 5.38.1"
 ```
 
 <!-- x-release-please-end -->

data/lib/telnyx/errors.rb

@@ -224,5 +224,15 @@ module Telnyx
     class InternalServerError < Telnyx::Errors::APIStatusError
       HTTP_STATUS = (500..)
     end
+
+    # Raised when webhook signature verification fails.
+    class WebhookVerificationError < Telnyx::Errors::Error
+      # @api private
+      #
+      # @param message [String]
+      def initialize(message:)
+        super(message)
+      end
+    end
   end
 end

data/lib/telnyx/resources/webhooks.rb

@@ -1,30 +1,213 @@
 # frozen_string_literal: true
 
+require "base64"
+require "json"
+require "openssl"
+
 module Telnyx
   module Resources
+    # Telnyx webhook verification using ED25519 signatures.
+    #
+    # This class provides ED25519 signature verification for Telnyx webhooks,
+    # matching the implementation pattern used in the Python and Node SDKs.
+    #
+    # Example usage:
+    #
+    #   client = Telnyx::Client.new(
+    #     api_key: ENV["TELNYX_API_KEY"],
+    #     public_key: ENV["TELNYX_PUBLIC_KEY"]  # Base64 from Mission Control
+    #   )
+    #
+    #   # In your webhook handler:
+    #   event = client.webhooks.unwrap(payload, headers)
+    #
     class Webhooks
+      # Telnyx webhook signature headers (case-insensitive per HTTP spec)
+      SIGNATURE_HEADER = "telnyx-signature-ed25519"
+      TIMESTAMP_HEADER = "telnyx-timestamp"
+
+      # Tolerance for timestamp validation (5 minutes)
+      TIMESTAMP_TOLERANCE_SECONDS = 300
+
+      # Unwraps a webhook event from its JSON representation without verifying the signature.
+      #
       # @param payload [String] The raw webhook payload as a string
       #
-      # @return [Telnyx::Models::CallAIGatherEndedWebhookEvent, Telnyx::Models::CallAIGatherMessageHistoryUpdatedWebhookEvent, Telnyx::Models::CallAIGatherPartialResultsWebhookEvent, Telnyx::Models::CallAnsweredWebhookEvent, Telnyx::Models::CallBridgedWebhookEvent, Telnyx::Models::CallConversationEndedWebhookEvent, Telnyx::Models::CallConversationInsightsGeneratedWebhookEvent, Telnyx::Models::CallDtmfReceivedWebhookEvent, Telnyx::Models::CallEnqueuedWebhookEvent, Telnyx::Models::CallForkStartedWebhookEvent, Telnyx::Models::CallForkStoppedWebhookEvent, Telnyx::Models::CallGatherEndedWebhookEvent, Telnyx::Models::CallHangupWebhookEvent, Telnyx::Models::CallInitiatedWebhookEvent, Telnyx::Models::CallLeftQueueWebhookEvent, Telnyx::Models::CallMachineDetectionEndedWebhookEvent, Telnyx::Models::CallMachineGreetingEndedWebhookEvent, Telnyx::Models::CallMachinePremiumDetectionEndedWebhookEvent, Telnyx::Models::CallMachinePremiumGreetingEndedWebhookEvent, Telnyx::Models::CallPlaybackEndedWebhookEvent, Telnyx::Models::CallPlaybackStartedWebhookEvent, Telnyx::Models::CallRecordingErrorWebhookEvent, Telnyx::Models::CallRecordingSavedWebhookEvent, Telnyx::Models::CallRecordingTranscriptionSavedWebhookEvent, Telnyx::Models::CallReferCompletedWebhookEvent, Telnyx::Models::CallReferFailedWebhookEvent, Telnyx::Models::CallReferStartedWebhookEvent, Telnyx::Models::CallSiprecFailedWebhookEvent, Telnyx::Models::CallSiprecStartedWebhookEvent, Telnyx::Models::CallSiprecStoppedWebhookEvent, Telnyx::Models::CallSpeakEndedWebhookEvent, Telnyx::Models::CallSpeakStartedWebhookEvent, Telnyx::Models::CallStreamingFailedWebhookEvent, Telnyx::Models::CallStreamingStartedWebhookEvent, Telnyx::Models::CallStreamingStoppedWebhookEvent, Telnyx::Models::CampaignStatusUpdate, Telnyx::Models::ConferenceCreatedWebhookEvent, Telnyx::Models::ConferenceEndedWebhookEvent, Telnyx::Models::ConferenceFloorChanged, Telnyx::Models::ConferenceParticipantJoinedWebhookEvent, Telnyx::Models::ConferenceParticipantLeftWebhookEvent, Telnyx::Models::ConferenceParticipantPlaybackEndedWebhookEvent, Telnyx::Models::ConferenceParticipantPlaybackStartedWebhookEvent, Telnyx::Models::ConferenceParticipantSpeakEndedWebhookEvent, Telnyx::Models::ConferenceParticipantSpeakStartedWebhookEvent, Telnyx::Models::ConferencePlaybackEndedWebhookEvent, Telnyx::Models::ConferencePlaybackStartedWebhookEvent, Telnyx::Models::ConferenceRecordingSavedWebhookEvent, Telnyx::Models::ConferenceSpeakEndedWebhookEvent, Telnyx::Models::ConferenceSpeakStartedWebhookEvent, Telnyx::Models::DeliveryUpdateWebhookEvent, Telnyx::Models::FaxDelivered, Telnyx::Models::FaxFailed, Telnyx::Models::FaxMediaProcessed, Telnyx::Models::FaxQueued, Telnyx::Models::FaxSendingStarted, Telnyx::Models::InboundMessageWebhookEvent, Telnyx::Models::NumberOrderStatusUpdate, Telnyx::Models::ReplacedLinkClickWebhookEvent, Telnyx::Models::TranscriptionWebhookEvent]
+      # @return [Telnyx::Models::UnsafeUnwrapWebhookEvent]
       def unsafe_unwrap(payload)
         parsed = JSON.parse(payload, symbolize_names: true)
         Telnyx::Internal::Type::Converter.coerce(Telnyx::Models::UnsafeUnwrapWebhookEvent, parsed)
       end
 
+      # Unwraps a webhook event from its JSON representation, verifying the signature if headers are provided.
+      #
+      # When headers are provided and the client has a public_key configured, this method will verify
+      # the ED25519 signature to ensure the webhook came from Telnyx.
+      #
       # @param payload [String] The raw webhook payload as a string
+      # @param headers [Hash, nil] Optional HTTP headers from the webhook request
+      # @param key [String, nil] Optional public key override (base64-encoded)
+      #
+      # @return [Telnyx::Models::UnwrapWebhookEvent]
       #
-      # @return [Telnyx::Models::CallAIGatherEndedWebhookEvent, Telnyx::Models::CallAIGatherMessageHistoryUpdatedWebhookEvent, Telnyx::Models::CallAIGatherPartialResultsWebhookEvent, Telnyx::Models::CallAnsweredWebhookEvent, Telnyx::Models::CallBridgedWebhookEvent, Telnyx::Models::CallConversationEndedWebhookEvent, Telnyx::Models::CallConversationInsightsGeneratedWebhookEvent, Telnyx::Models::CallDtmfReceivedWebhookEvent, Telnyx::Models::CallEnqueuedWebhookEvent, Telnyx::Models::CallForkStartedWebhookEvent, Telnyx::Models::CallForkStoppedWebhookEvent, Telnyx::Models::CallGatherEndedWebhookEvent, Telnyx::Models::CallHangupWebhookEvent, Telnyx::Models::CallInitiatedWebhookEvent, Telnyx::Models::CallLeftQueueWebhookEvent, Telnyx::Models::CallMachineDetectionEndedWebhookEvent, Telnyx::Models::CallMachineGreetingEndedWebhookEvent, Telnyx::Models::CallMachinePremiumDetectionEndedWebhookEvent, Telnyx::Models::CallMachinePremiumGreetingEndedWebhookEvent, Telnyx::Models::CallPlaybackEndedWebhookEvent, Telnyx::Models::CallPlaybackStartedWebhookEvent, Telnyx::Models::CallRecordingErrorWebhookEvent, Telnyx::Models::CallRecordingSavedWebhookEvent, Telnyx::Models::CallRecordingTranscriptionSavedWebhookEvent, Telnyx::Models::CallReferCompletedWebhookEvent, Telnyx::Models::CallReferFailedWebhookEvent, Telnyx::Models::CallReferStartedWebhookEvent, Telnyx::Models::CallSiprecFailedWebhookEvent, Telnyx::Models::CallSiprecStartedWebhookEvent, Telnyx::Models::CallSiprecStoppedWebhookEvent, Telnyx::Models::CallSpeakEndedWebhookEvent, Telnyx::Models::CallSpeakStartedWebhookEvent, Telnyx::Models::CallStreamingFailedWebhookEvent, Telnyx::Models::CallStreamingStartedWebhookEvent, Telnyx::Models::CallStreamingStoppedWebhookEvent, Telnyx::Models::CampaignStatusUpdate, Telnyx::Models::ConferenceCreatedWebhookEvent, Telnyx::Models::ConferenceEndedWebhookEvent, Telnyx::Models::ConferenceFloorChanged, Telnyx::Models::ConferenceParticipantJoinedWebhookEvent, Telnyx::Models::ConferenceParticipantLeftWebhookEvent, Telnyx::Models::ConferenceParticipantPlaybackEndedWebhookEvent, Telnyx::Models::ConferenceParticipantPlaybackStartedWebhookEvent, Telnyx::Models::ConferenceParticipantSpeakEndedWebhookEvent, Telnyx::Models::ConferenceParticipantSpeakStartedWebhookEvent, Telnyx::Models::ConferencePlaybackEndedWebhookEvent, Telnyx::Models::ConferencePlaybackStartedWebhookEvent, Telnyx::Models::ConferenceRecordingSavedWebhookEvent, Telnyx::Models::ConferenceSpeakEndedWebhookEvent, Telnyx::Models::ConferenceSpeakStartedWebhookEvent, Telnyx::Models::DeliveryUpdateWebhookEvent, Telnyx::Models::FaxDelivered, Telnyx::Models::FaxFailed, Telnyx::Models::FaxMediaProcessed, Telnyx::Models::FaxQueued, Telnyx::Models::FaxSendingStarted, Telnyx::Models::InboundMessageWebhookEvent, Telnyx::Models::NumberOrderStatusUpdate, Telnyx::Models::ReplacedLinkClickWebhookEvent, Telnyx::Models::TranscriptionWebhookEvent]
-      def unwrap(payload)
+      # @raise [Telnyx::Errors::WebhookVerificationError] If signature verification fails
+      def unwrap(payload, headers = nil, key: nil)
+        # Get public key from argument or client
+        public_key = key || @client.public_key
+
+        # If we have headers and a public key, verify the signature
+        if headers && !headers.empty? && public_key && !public_key.empty?
+          verify_signature(payload, headers, public_key)
+        end
+
         parsed = JSON.parse(payload, symbolize_names: true)
         Telnyx::Internal::Type::Converter.coerce(Telnyx::Models::UnwrapWebhookEvent, parsed)
       end
 
+      # Verify webhook signature without parsing the payload.
+      #
+      # This method is consistent with the Node SDK's verify() method, allowing
+      # signature verification without parsing the webhook payload. The bang (!)
+      # indicates this method raises an exception on failure (Ruby convention).
+      #
+      # @param payload [String] The raw webhook payload
+      # @param headers [Hash] The webhook headers
+      # @param key [String, nil] Optional public key override (base64-encoded)
+      #
+      # @return [void]
+      #
+      # @raise [Telnyx::Errors::WebhookVerificationError] If verification fails or no public key available
+      def verify!(payload, headers, key: nil)
+        public_key = key || @client.public_key
+
+        unless public_key && !public_key.empty?
+          raise Telnyx::Errors::WebhookVerificationError.new(
+            message: "No public key configured. Provide key parameter or configure client with public_key."
+          )
+        end
+
+        verify_signature(payload, headers, public_key)
+      end
+
       # @api private
       #
       # @param client [Telnyx::Client]
       def initialize(client:)
         @client = client
       end
+
+      private
+
+      # Get header value case-insensitively
+      #
+      # @param headers [Hash] The headers hash
+      # @param key [String] The header key to find
+      #
+      # @return [String, nil]
+      def get_header(headers, key)
+        key_lower = key.downcase
+        headers.each do |header_key, header_value|
+          return header_value if header_key.to_s.downcase == key_lower
+        end
+        nil
+      end
+
+      # Verify the webhook signature using ED25519 cryptography
+      #
+      # @param payload [String] The raw webhook payload
+      # @param headers [Hash] The webhook headers
+      # @param public_key [String] The ED25519 public key (base64-encoded)
+      #
+      # @raise [Telnyx::Errors::WebhookVerificationError] If verification fails
+      def verify_signature(payload, headers, public_key)
+        # Extract required headers (case-insensitive)
+        signature_header = get_header(headers, SIGNATURE_HEADER)
+        timestamp_header = get_header(headers, TIMESTAMP_HEADER)
+
+        unless signature_header
+          raise Telnyx::Errors::WebhookVerificationError.new(
+            message: "Missing required header: #{SIGNATURE_HEADER}"
+          )
+        end
+
+        unless timestamp_header
+          raise Telnyx::Errors::WebhookVerificationError.new(
+            message: "Missing required header: #{TIMESTAMP_HEADER}"
+          )
+        end
+
+        # Validate timestamp to prevent replay attacks (5 minute tolerance)
+        begin
+          webhook_time = Integer(timestamp_header)
+          current_time = Time.now.to_i
+          time_diff = (current_time - webhook_time).abs
+
+          if time_diff > TIMESTAMP_TOLERANCE_SECONDS
+            raise Telnyx::Errors::WebhookVerificationError.new(
+              message: "Webhook timestamp is too old or too new (#{time_diff}s difference)"
+            )
+          end
+        rescue ArgumentError
+          raise Telnyx::Errors::WebhookVerificationError.new(
+            message: "Invalid timestamp format: #{timestamp_header}"
+          )
+        end
+
+        # Decode public key from base64
+        begin
+          public_key_bytes = Base64.strict_decode64(public_key)
+
+          if public_key_bytes.bytesize != 32
+            raise Telnyx::Errors::WebhookVerificationError.new(
+              message: "Invalid public key: expected 32 bytes, got #{public_key_bytes.bytesize} bytes"
+            )
+          end
+        rescue ArgumentError => e
+          raise Telnyx::Errors::WebhookVerificationError.new(
+            message: "Invalid public key format: #{e.message}"
+          )
+        end
+
+        # Decode signature from base64
+        begin
+          signature_bytes = Base64.strict_decode64(signature_header)
+
+          if signature_bytes.bytesize != 64
+            raise Telnyx::Errors::WebhookVerificationError.new(
+              message: "Invalid signature length: expected 64 bytes, got #{signature_bytes.bytesize} bytes"
+            )
+          end
+        rescue ArgumentError => e
+          raise Telnyx::Errors::WebhookVerificationError.new(
+            message: "Invalid signature format: #{e.message}"
+          )
+        end
+
+        # Create the signed payload: timestamp|payload
+        signed_payload = "#{timestamp_header}|#{payload}"
+
+        # Build ED25519 public key for verification
+        # The raw 32-byte key needs to be wrapped in X.509 SubjectPublicKeyInfo format
+        # ED25519 OID: 1.3.101.112 = 06 03 2b 65 70
+        # X.509 SPKI header for ED25519: 30 2a 30 05 06 03 2b 65 70 03 21 00
+        ed25519_spki_header = [0x30, 0x2a, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x03, 0x21, 0x00].pack("C*")
+        der_key = ed25519_spki_header + public_key_bytes
+
+        begin
+          pkey = OpenSSL::PKey.read(der_key)
+          valid = pkey.verify(nil, signature_bytes, signed_payload)
+
+          unless valid
+            raise Telnyx::Errors::WebhookVerificationError.new(
+              message: "Signature verification failed: signature does not match payload"
+            )
+          end
+        rescue OpenSSL::PKey::PKeyError => e
+          raise Telnyx::Errors::WebhookVerificationError.new(
+            message: "Signature verification failed: #{e.message}"
+          )
+        end
+      end
     end
   end
 end

data/lib/telnyx/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Telnyx
-  VERSION = "5.38.0"
+  VERSION = "5.38.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: telnyx
 version: !ruby/object:Gem::Version
-  version: 5.38.0
+  version: 5.38.1
 platform: ruby
 authors:
 - Telnyx