Vonage Utilities

Common errors

• ModuleNotFoundError: No module named '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.
  fix If you intend to use the full Vonage API SDK, install it explicitly: `pip install vonage`.

• AttributeError: 'Client' object has no attribute 'sms'

  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`.
  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.

• TypeError: check_signature() missing 1 required positional argument: 'signature_text'

  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.
  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)`.

Warnings

• gotcha 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.
  Fix: For full Vonage API interaction, install `vonage` (`pip install vonage`) and import `Client` from `vonage`.
• gotcha 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.
  Fix: If you need to send messages or interact with specific Vonage APIs using convenience methods, use `from vonage import Client` after installing `vonage`.
• gotcha 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.
  Fix: Locate your 'SIGNATURE_SECRET' in the Vonage Dashboard under 'API Settings' and use that specific secret string when initializing `SignatureVerification`.

Install

• pip install vonage-utils Install vonage-utils

Imports

• Client
  wrong:

  from vonage import Client

  correct:

  from vonage_utils.client import Client

  This is the base HTTP client from vonage-utils, not the full API client from the main vonage-python-sdk.
• SignatureVerification

  from vonage_utils.signature import SignatureVerification

• VonageError

  from vonage_utils.errors import VonageError

Quickstart

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.

import os
from vonage_utils.signature import SignatureVerification

# Replace with your actual signature secret from Vonage API dashboard
# For example, store it in an environment variable named VONAGE_SIGNATURE_SECRET
VONAGE_SIGNATURE_SECRET = os.environ.get("VONAGE_SIGNATURE_SECRET", "YOUR_SIGNATURE_SECRET")

if VONAGE_SIGNATURE_SECRET == "YOUR_SIGNATURE_SECRET":
    print("WARNING: Please set the VONAGE_SIGNATURE_SECRET environment variable or replace 'YOUR_SIGNATURE_SECRET' with your actual secret.")

# Example webhook payload (as a raw string, as received by your server)
webhook_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"}'

# Example X-Vonage-Signature header value received with the webhook
# This value is a hash calculated by Vonage based on the payload and your secret.
# (The example below is a placeholder; a real one would be dynamically generated.)
vonage_signature = "e10adc3949ba59abbe56e057f20f883e" # Placeholder: MD5 hash of "Hello World" for illustration

verifier = SignatureVerification(VONAGE_SIGNATURE_SECRET)

# To verify an incoming webhook signature
is_valid = verifier.check_signature(webhook_payload, vonage_signature)

if is_valid:
    print("Signature is valid! The webhook can be trusted.")
else:
    print("Signature is invalid! The webhook might be tampered with or is not from Vonage.")

# For actual production use:
# - Ensure VONAGE_SIGNATURE_SECRET is your correct secret.
# - `webhook_payload` must be the exact raw request body.
# - `vonage_signature` must be the exact value from the 'X-Vonage-Signature' HTTP header.