telnyx 3.8.0__py3-none-any.whl → 3.9.0__py3-none-any.whl

telnyx/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "telnyx"
-__version__ = "3.8.0"  # x-release-please-version
+__version__ = "3.9.0"  # x-release-please-version

telnyx/resources/__init__.py

@@ -224,7 +224,7 @@ from .portouts import (
     PortoutsResourceWithStreamingResponse,
     AsyncPortoutsResourceWithStreamingResponse,
 )
-from .webhooks import WebhooksResource, AsyncWebhooksResource
+from .webhooks import TelnyxWebhook, WebhooksResource, AsyncWebhooksResource, TelnyxWebhookVerificationError
 from .wireless import (
     WirelessResource,
     AsyncWirelessResource,
@@ -1237,6 +1237,8 @@ __all__ = [
     "AsyncOAuthGrantsResourceWithStreamingResponse",
     "WebhooksResource",
     "AsyncWebhooksResource",
+    "TelnyxWebhook",
+    "TelnyxWebhookVerificationError",
     "AccessIPAddressResource",
     "AsyncAccessIPAddressResource",
     "AccessIPAddressResourceWithRawResponse",

telnyx/resources/webhooks.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import json
 from typing import Mapping, cast
+from datetime import datetime, timezone
 
 from .._models import construct_type
 from .._resource import SyncAPIResource, AsyncAPIResource
@@ -11,7 +12,106 @@ from .._exceptions import TelnyxError
 from ..types.unwrap_webhook_event import UnwrapWebhookEvent
 from ..types.unsafe_unwrap_webhook_event import UnsafeUnwrapWebhookEvent
 
-__all__ = ["WebhooksResource", "AsyncWebhooksResource"]
+__all__ = ["WebhooksResource", "AsyncWebhooksResource", "TelnyxWebhook", "TelnyxWebhookVerificationError"]
+
+
+class TelnyxWebhookVerificationError(TelnyxError):
+    """Raised when webhook verification fails."""
+    pass
+
+
+class TelnyxWebhook:
+    """
+    Telnyx webhook verification following the standardwebhooks pattern.
+    
+    This class provides ED25519 signature verification for Telnyx webhooks
+    using the same interface pattern as the standardwebhooks library.
+    """
+    
+    def __init__(self, key: str | bytes):
+        """
+        Initialize the webhook verifier with a public key.
+        
+        Args:
+            key: The public key for verification (hex string or bytes)
+        """
+        try:
+            from nacl.signing import VerifyKey
+        except ImportError as exc:
+            raise TelnyxError("You need to install `pynacl` to verify Telnyx webhooks") from exc
+        
+        # Convert key to bytes if it's a string
+        if isinstance(key, str):
+            try:
+                key = bytes.fromhex(key)  # Convert from hex string to bytes
+            except ValueError as exc:
+                raise TelnyxWebhookVerificationError(f"Invalid key format: {key!r}") from exc
+        
+        self._verify_key = VerifyKey(key)
+    
+    def verify(self, payload: str, headers: Mapping[str, str]) -> None:
+        """
+        Verify a webhook payload and headers.
+        
+        Args:
+            payload: The webhook payload string
+            headers: The webhook headers
+            
+        Raises:
+            TelnyxWebhookVerificationError: If verification fails
+        """
+        try:
+            from nacl.exceptions import BadSignatureError
+        except ImportError as exc:
+            raise TelnyxError("You need to install `pynacl` to verify Telnyx webhooks") from exc
+        
+        # Extract required headers (case-insensitive lookup)
+        signature_header = headers.get("Telnyx-Signature-Ed25519") or headers.get("telnyx-signature-ed25519")
+        timestamp_header = headers.get("Telnyx-Timestamp") or headers.get("telnyx-timestamp")
+        user_agent = headers.get("User-Agent") or headers.get("user-agent", "")
+
+        # Validate required headers
+        if not signature_header:
+            raise TelnyxWebhookVerificationError("Missing required header: Telnyx-Signature-Ed25519")
+        
+        if not timestamp_header:
+            raise TelnyxWebhookVerificationError("Missing required header: Telnyx-Timestamp")
+
+        # Verify User-Agent if present (optional security check)
+        if user_agent and "telnyx-webhooks" not in user_agent.lower():
+            raise TelnyxWebhookVerificationError(f"Unexpected User-Agent: {user_agent}")
+
+        # Validate timestamp format and prevent replay attacks
+        try:
+            webhook_time = int(timestamp_header)
+            current_time = int(datetime.now(timezone.utc).timestamp())
+            
+            # Allow 5 minutes tolerance
+            if abs(current_time - webhook_time) > 300:
+                raise TelnyxWebhookVerificationError(
+                    f"Webhook timestamp too old or too new: {timestamp_header}"
+                )
+        except ValueError as exc:
+            raise TelnyxWebhookVerificationError(
+                f"Invalid timestamp format: {timestamp_header}"
+            ) from exc
+
+        # Decode the signature from hex
+        try:
+            signature = bytes.fromhex(signature_header)
+        except ValueError as exc:
+            raise TelnyxWebhookVerificationError(
+                f"Invalid signature format: {signature_header}"
+            ) from exc
+
+        # Create the signed payload: timestamp + payload
+        signed_payload = timestamp_header.encode('utf-8') + payload.encode('utf-8')
+
+        # Verify the signature
+        try:
+            self._verify_key.verify(signed_payload, signature)
+        except BadSignatureError as exc:
+            raise TelnyxWebhookVerificationError("Invalid webhook signature") from exc
 
 
 class WebhooksResource(SyncAPIResource):
@@ -25,11 +125,6 @@ class WebhooksResource(SyncAPIResource):
         )
 
     def unwrap(self, payload: str, *, headers: Mapping[str, str], key: str | bytes | None = None) -> UnwrapWebhookEvent:
-        try:
-            from standardwebhooks import Webhook
-        except ImportError as exc:
-            raise TelnyxError("You need to install `telnyx[webhooks]` to use this method") from exc
-
         if key is None:
             key = self._client.public_key
             if key is None:
@@ -40,7 +135,9 @@ class WebhooksResource(SyncAPIResource):
         if not isinstance(headers, dict):
             headers = dict(headers)
 
-        Webhook(key).verify(payload, headers)
+        # Use Telnyx-specific webhook verification following standardwebhooks pattern
+        webhook = TelnyxWebhook(key)
+        webhook.verify(payload, headers)
 
         return cast(
             UnwrapWebhookEvent,
@@ -62,11 +159,6 @@ class AsyncWebhooksResource(AsyncAPIResource):
         )
 
     def unwrap(self, payload: str, *, headers: Mapping[str, str], key: str | bytes | None = None) -> UnwrapWebhookEvent:
-        try:
-            from standardwebhooks import Webhook
-        except ImportError as exc:
-            raise TelnyxError("You need to install `telnyx[webhooks]` to use this method") from exc
-
         if key is None:
             key = self._client.public_key
             if key is None:
@@ -77,7 +169,9 @@ class AsyncWebhooksResource(AsyncAPIResource):
         if not isinstance(headers, dict):
             headers = dict(headers)
 
-        Webhook(key).verify(payload, headers)
+        # Use Telnyx-specific webhook verification following standardwebhooks pattern
+        webhook = TelnyxWebhook(key)
+        webhook.verify(payload, headers)
 
         return cast(
             UnwrapWebhookEvent,

{telnyx-3.8.0.dist-info → telnyx-3.9.0.dist-info}/METADATA

@@ -1,11 +1,12 @@
 Metadata-Version: 2.3
 Name: telnyx
-Version: 3.8.0
-Summary: The official Python library for the telnyx API
+Version: 3.9.0
+Summary: Telnyx API SDK for global Voice, SMS, MMS, WhatsApp, Fax, Wireless IoT, SIP Trunking, and Call Control.
 Project-URL: Homepage, https://github.com/team-telnyx/telnyx-python
 Project-URL: Repository, https://github.com/team-telnyx/telnyx-python
 Author-email: Telnyx <support@telnyx.com>
 License: MIT
+Keywords: api,communications,connectivity,fax,iot,mms,sip,sms,telephony,telnyx,trunking,voice,voip,whatsapp
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: MacOS
@@ -32,6 +33,7 @@ Provides-Extra: aiohttp
 Requires-Dist: aiohttp; extra == 'aiohttp'
 Requires-Dist: httpx-aiohttp>=0.1.9; extra == 'aiohttp'
 Provides-Extra: webhooks
+Requires-Dist: pynacl>=1.5.0; extra == 'webhooks'
 Requires-Dist: standardwebhooks; extra == 'webhooks'
 Description-Content-Type: text/markdown
 

{telnyx-3.8.0.dist-info → telnyx-3.9.0.dist-info}/RECORD

@@ -11,7 +11,7 @@ telnyx/_resource.py,sha256=B4Qg-uO2a34FQHHZskn89eVURqMuSvv1TdeBJH1z1rU,1100
 telnyx/_response.py,sha256=4X24wr7uQn2hnM_b0xqQ92zSgxRFFfWG2lTg93-KzNo,28788
 telnyx/_streaming.py,sha256=OfSFcMQJ_mnvfkbIdOG7Ajp0SMbXnOJSga4xXHjNAJk,10100
 telnyx/_types.py,sha256=Du3G2vdqeLhhdJZ4Jtck4vOqEvAKI9rB1FnrwB1b_k8,7236
-telnyx/_version.py,sha256=lwpU2hAJbxRw1J5zKphT95CVY5KhP9FxxxnGrX2ydns,158
+telnyx/_version.py,sha256=yO7Mq2vTSOGHLfystQT0aBZqhiqyLnH7G4MvkMkg3l8,158
 telnyx/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 telnyx/_utils/__init__.py,sha256=7fch0GT9zpNnErbciSpUNa-SjTxxjY6kxHxKMOM4AGs,2305
 telnyx/_utils/_compat.py,sha256=D8gtAvjJQrDWt9upS0XaG9Rr5l1QhiAx_I_1utT_tt0,1195
@@ -26,7 +26,7 @@ telnyx/_utils/_transform.py,sha256=NjCzmnfqYrsAikUHQig6N9QfuTVbKipuP3ur9mcNF-E,1
 telnyx/_utils/_typing.py,sha256=N_5PPuFNsaygbtA_npZd98SVN1LQQvFTKL6bkWPBZGU,4786
 telnyx/_utils/_utils.py,sha256=0dDqauUbVZEXV0NVl7Bwu904Wwo5eyFCZpQThhFNhyA,12253
 telnyx/lib/.keep,sha256=wuNrz-5SXo3jJaJOJgz4vFHM41YH_g20F5cRQo0vLes,224
-telnyx/resources/__init__.py,sha256=YdEPEfdK5zpqzCb5JF9PzIMDBqK9P14TUvHuDuQXVww,86014
+telnyx/resources/__init__.py,sha256=kuejh4nn9SnMB6yXv44iqiub-rauIjl84hSFetcvG3M,86120
 telnyx/resources/access_ip_address.py,sha256=GHrKaYv0pxX2NrECShHPxibCq1mpXXEOOTXFSTDNUVQ,17519
 telnyx/resources/access_ip_ranges.py,sha256=Xb9w6OlrM6aphz9CfktBZDvespX13tLQWMiZFK46JN0,14210
 telnyx/resources/advanced_orders.py,sha256=zHasSS2AwBk1K7GuxX5Vm9DjCbX5kwS3G-Q1M2p19vk,18707
@@ -134,7 +134,7 @@ telnyx/resources/verify_profiles.py,sha256=p04zuJk1_we5Ez6OyRVq-KE1EALdgVjzmXukG
 telnyx/resources/virtual_cross_connects.py,sha256=JDAXB9dhVNn-qAiTyNDAgYELHdFwGoqS6yM5l4NrDZA,34715
 telnyx/resources/virtual_cross_connects_coverage.py,sha256=LE0l4hJJCO8jsaanpA85fa_wGNHgsZO4yPpf1RoNRCQ,9320
 telnyx/resources/webhook_deliveries.py,sha256=PKo-2i1Ndhe3i7zozog3d0Ko5dznDshsOqLeogdXah0,11174
-telnyx/resources/webhooks.py,sha256=Z25U-Umbj3DlGMsoSozv_ULe_dwmoL9oZ2FuuuQNkbA,2944
+telnyx/resources/webhooks.py,sha256=_6mEpkZNk9qYpRhbY6sPEqaiUkOiZjiCUo1JPBKOJys,6763
 telnyx/resources/well_known.py,sha256=3Nm9gDqj9nDawaMoSj-yy3z_3dhDdBjK0NqOR0NJg4I,8881
 telnyx/resources/wireguard_interfaces.py,sha256=wxfoFKlIQ4We6Zi9huXfN2Y_xAYZN5_IK6ziEGggM4I,18414
 telnyx/resources/wireguard_peers.py,sha256=FefL6ivnxn6uq2vJY6hvzCzTm1wlqWiifc4D81QYSSE,24615
@@ -2096,7 +2096,7 @@ telnyx/types/wireless/detail_records_report_list_params.py,sha256=cfjsh4L_8mpDkg
 telnyx/types/wireless/detail_records_report_list_response.py,sha256=S_6nD0fm5EseRIZHnML-UN0-g8Q_0J1cXfg_eLNUev8,331
 telnyx/types/wireless/detail_records_report_retrieve_response.py,sha256=f0C8z8uo_QeCyi3nSDME4f4F3vqcy7o0MpinwDIqe_s,327
 telnyx/types/wireless/wdr_report.py,sha256=bxRr-dc_IW6D0E3i_PUHK-bbu9w114Qql1uoJ_znxEE,1068
-telnyx-3.8.0.dist-info/METADATA,sha256=ODFtLiKVlZYhyzYvN7SI5CyEl3lra5IFqZK2W8rr2pM,15608
-telnyx-3.8.0.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
-telnyx-3.8.0.dist-info/licenses/LICENSE,sha256=PprdXvskBJR41_t2uhgs5rHYGME_Ek-lh2PAxKtdZs8,1046
-telnyx-3.8.0.dist-info/RECORD,,
+telnyx-3.9.0.dist-info/METADATA,sha256=9Py7FhgBTlrRKMb8HgttIgL5imGDe79WNGvnaddz-bY,15823
+telnyx-3.9.0.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
+telnyx-3.9.0.dist-info/licenses/LICENSE,sha256=PprdXvskBJR41_t2uhgs5rHYGME_Ek-lh2PAxKtdZs8,1046
+telnyx-3.9.0.dist-info/RECORD,,