{"id":8767,"library":"vonage-utils","title":"Vonage Utilities","description":"The `vonage-utils` library provides foundational utility objects for interacting with Vonage APIs, including a base HTTP client, error handling, and signature verification. It is currently at version `1.1.4` and serves as a low-level dependency for the `vonage-python-sdk`, which is more frequently updated. While usable independently, most users interact with the higher-level SDK for full API functionality.","status":"active","version":"1.1.4","language":"en","source_language":"en","source_url":"https://github.com/Vonage/vonage-python-sdk","tags":["vonage","utility","webhook","signature-verification","client","sdk"],"install":[{"cmd":"pip install vonage-utils","lang":"bash","label":"Install vonage-utils"}],"dependencies":[{"reason":"Used for making HTTP requests.","package":"requests","optional":false},{"reason":"Used for JSON Web Token (JWT) handling.","package":"pyjwt","optional":false},{"reason":"Provides cryptographic primitives, likely for signature verification.","package":"cryptography","optional":false},{"reason":"Used for data validation and parsing.","package":"pydantic","optional":false}],"imports":[{"note":"This is the base HTTP client from vonage-utils, not the full API client from the main vonage-python-sdk.","wrong":"from vonage import Client","symbol":"Client","correct":"from vonage_utils.client import Client"},{"symbol":"SignatureVerification","correct":"from vonage_utils.signature import SignatureVerification"},{"symbol":"VonageError","correct":"from vonage_utils.errors import VonageError"}],"quickstart":{"code":"import os\nfrom vonage_utils.signature import SignatureVerification\n\n# Replace with your actual signature secret from Vonage API dashboard\n# For example, store it in an environment variable named VONAGE_SIGNATURE_SECRET\nVONAGE_SIGNATURE_SECRET = os.environ.get(\"VONAGE_SIGNATURE_SECRET\", \"YOUR_SIGNATURE_SECRET\")\n\nif VONAGE_SIGNATURE_SECRET == \"YOUR_SIGNATURE_SECRET\":\n    print(\"WARNING: Please set the VONAGE_SIGNATURE_SECRET environment variable or replace 'YOUR_SIGNATURE_SECRET' with your actual secret.\")\n\n# Example webhook payload (as a raw string, as received by your server)\nwebhook_payload = '{\"msisdn\":\"1234567890\",\"to\":\"19876543210\",\"messageId\":\"00000000-0000-0000-0000-000000000000\",\"text\":\"Hello World\",\"type\":\"text\",\"keyword\":\"HELLO\",\"api-key\":\"YOUR_API_KEY\",\"message-timestamp\":\"2023-10-27 10:00:00\"}'\n\n# Example X-Vonage-Signature header value received with the webhook\n# This value is a hash calculated by Vonage based on the payload and your secret.\n# (The example below is a placeholder; a real one would be dynamically generated.)\nvonage_signature = \"e10adc3949ba59abbe56e057f20f883e\" # Placeholder: MD5 hash of \"Hello World\" for illustration\n\nverifier = SignatureVerification(VONAGE_SIGNATURE_SECRET)\n\n# To verify an incoming webhook signature\nis_valid = verifier.check_signature(webhook_payload, vonage_signature)\n\nif is_valid:\n    print(\"Signature is valid! The webhook can be trusted.\")\nelse:\n    print(\"Signature is invalid! The webhook might be tampered with or is not from Vonage.\")\n\n# For actual production use:\n# - Ensure VONAGE_SIGNATURE_SECRET is your correct secret.\n# - `webhook_payload` must be the exact raw request body.\n# - `vonage_signature` must be the exact value from the 'X-Vonage-Signature' HTTP header.","lang":"python","description":"This quickstart demonstrates how to use the `SignatureVerification` class from `vonage-utils` to validate incoming Vonage webhook requests. This is crucial for securing your webhooks by ensuring the payload originated from Vonage and has not been altered."},"warnings":[{"fix":"For full Vonage API interaction, install `vonage` (`pip install vonage`) and import `Client` from `vonage`.","message":"The `vonage-utils` package is a foundational component of the `vonage-python-sdk`. While it can be installed and used independently, most users should primarily interact with the higher-level `vonage` package (the main SDK) for full API functionality, as `vonage-utils` only provides low-level building blocks.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If you need to send messages or interact with specific Vonage APIs using convenience methods, use `from vonage import Client` after installing `vonage`.","message":"The `Client` class imported from `vonage_utils.client` is a basic HTTP client. It does not provide the high-level API wrappers, convenience methods (e.g., `client.sms.send_message`), or automatic authentication mechanisms found in the `Client` class from the main `vonage` package. Attempting to call Vonage APIs directly through `vonage_utils.Client` will require manual URL construction, authentication, and request body management.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Locate your 'SIGNATURE_SECRET' in the Vonage Dashboard under 'API Settings' and use that specific secret string when initializing `SignatureVerification`.","message":"When using `SignatureVerification` for webhooks, the `secret` parameter expects the unique 'SIGNATURE_SECRET' found in your Vonage API Dashboard. Do not confuse this with your API Key or API Secret, as they are different credentials and will lead to invalid signature verification.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"If you intend to use the full Vonage API SDK, install it explicitly: `pip install vonage`.","cause":"You have installed `vonage-utils` but are trying to import the main `vonage` package (the Vonage Python SDK), which is a separate library.","error":"ModuleNotFoundError: No module named 'vonage'"},{"fix":"Install the main SDK (`pip install vonage`) and import `Client` from `vonage`: `from vonage import Client`. This client offers wrappers for various Vonage APIs.","cause":"You are using the `Client` class from `vonage-utils`, which is a low-level HTTP client, not the feature-rich `Client` from the main `vonage` SDK that provides specific API methods like `sms`.","error":"AttributeError: 'Client' object has no attribute 'sms'"},{"fix":"Ensure you pass the raw request body and the value of the `X-Vonage-Signature` header to `check_signature()`: `verifier.check_signature(raw_request_body, x_vonage_signature_header_value)`.","cause":"The `SignatureVerification.check_signature()` method requires both the raw webhook `payload` (as a string) and the `signature_text` (from the `X-Vonage-Signature` header) in addition to the `signature_secret` provided during initialization.","error":"TypeError: check_signature() missing 1 required positional argument: 'signature_text'"}]}