Ruby SDK webhooks

Telnyx signs every webhook delivery with an ED25519 signature carried in the telnyx-signature-ed25519 and telnyx-timestamp request headers. The SDK’s webhook helper verifies the signature against your account’s public key and parses the payload into a typed event. Copy your public key from the Mission Control Portal and expose it as TELNYX_PUBLIC_KEY — the client reads it automatically, the same way it reads TELNYX_API_KEY:

export TELNYX_PUBLIC_KEY="..."

Verify and parse an event

Pass the raw request body and the request headers to client.webhooks.unwrap. Rack prefixes and upcases incoming header names, so convert them back before passing them in:

require "sinatra"
require "telnyx"

client = Telnyx::Client.new # reads TELNYX_API_KEY and TELNYX_PUBLIC_KEY

post "/webhooks/telnyx" do
  payload = request.body.read
  headers = request.env
    .select { |name, _| name.start_with?("HTTP_") }
    .transform_keys { |name| name.delete_prefix("HTTP_").downcase.tr("_", "-") }

  begin
    event = client.webhooks.unwrap(payload, headers: headers)
  rescue StandardError
    halt 400 # signature invalid or payload malformed
  end

  puts event.data.event_type
  200
end

unwrap raises when the signature does not match, and returns the parsed event as a typed union of every webhook event the API sends — check event.data.event_type to handle specific events.

Skipping verification

client.webhooks.unsafe_unwrap(payload) parses a payload without checking the signature. Only use it for payloads you have already verified by other means, or in tests.

Receiving webhooks covers delivery, retries, and failover URLs.
Errors, retries, and timeouts covers the SDK’s error classes.

Account setup

APIs fundamentals

Server-side SDKs

Telnyx CLI

Development Tools

Migration Guides

Glossary

For AI Agents

Ruby SDK webhooks

Verify and parse an event

Skipping verification

​Verify and parse an event

​Skipping verification

​Related

Verify and parse an event

Skipping verification

Related