Class: Telnyx::Resources::Webhooks

Inherits:
Object
  • Object
show all
Defined in:
lib/telnyx/resources/webhooks.rb

Overview

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)

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

Constructor Details

#initialize(client:) ⇒ Webhooks

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Webhooks.

Parameters:



95
96
97
 
# File 'lib/telnyx/resources/webhooks.rb', line 95

def initialize(client:)
  @client = client
end

Instance Method Details

#unsafe_unwrap(payload) ⇒ Telnyx::Models::UnsafeUnwrapWebhookEvent

Unwraps a webhook event from its JSON representation without verifying the signature.

Parameters:

  • payload (String) —

    The raw webhook payload as a string

Returns:



37
38
39
40
 
# File 'lib/telnyx/resources/webhooks.rb', line 37

def unsafe_unwrap(payload)
  parsed = JSON.parse(payload, symbolize_names: true)
  Telnyx::Internal::Type::Converter.coerce(Telnyx::Models::UnsafeUnwrapWebhookEvent, parsed)
end

#unwrap(payload, headers = nil, key: nil) ⇒ Telnyx::Models::UnwrapWebhookEvent

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.

Parameters:

  • payload (String) —

    The raw webhook payload as a string

  • headers (Hash, nil) (defaults to: nil) —

    Optional HTTP headers from the webhook request

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

    Optional public key override (base64-encoded)

Returns:

Raises:



54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/telnyx/resources/webhooks.rb', line 54

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!(payload, headers, key: nil) ⇒ void

This method returns an undefined value.

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

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:



80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/telnyx/resources/webhooks.rb', line 80

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