Module: Telnyx::Lib::WebhookVerification

Included in:
Resources::Webhooks
Defined in:
lib/telnyx/lib/webhook_verification.rb

Overview

Telnyx webhook verification using ED25519 signatures.

This module provides ED25519 signature verification for Telnyx webhooks, matching the implementation pattern used in the Python and Node SDKs.

The module is kept separate from generated code to avoid merge conflicts when Stainless updates webhook event types.

Example usage:

client = Telnyx::Client.new(
  api_key: ENV["TELNYX_API_KEY"],
  public_key: ENV["TELNYX_PUBLIC_KEY"]  # Base64 from Mission Control
)

# Verify signature only
client.webhooks.verify!(payload, headers)

# Verify and parse
event = client.webhooks.unwrap(payload, headers)

Constant Summary collapse

SIGNATURE_HEADER =

Telnyx webhook signature headers (case-insensitive per HTTP spec)

"telnyx-signature-ed25519"
TIMESTAMP_HEADER = 
"telnyx-timestamp"
TIMESTAMP_TOLERANCE_SECONDS =

Tolerance for timestamp validation (5 minutes)

300

Instance Method Summary collapse

Instance Method Details

#verify!(payload, headers, key: nil) ⇒ void

This method returns an undefined value.

Verify webhook signature without parsing the payload.

Parameters:

  • payload (String) —

    The raw webhook payload

  • headers (Hash) —

    The webhook headers

  • key (String, nil) (defaults to: nil) —

    Optional public key override (base64-encoded)

Raises:



47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/telnyx/lib/webhook_verification.rb', line 47

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

  do_verify_signature(payload, headers, public_key)
end