telnyx-webhooks

Telnyx Webhooks

When to Use This Skill

• How do I receive Telnyx webhooks?
• How do I verify Telnyx webhook signatures?
• How do I verify the telnyx-signature-ed25519 / telnyx-timestamp headers?
• How do I handle message.received, message.sent, or message.finalized events?
• Why is my Telnyx webhook signature verification failing?

Verification (core)

Telnyx Webhook API v2 signs every event with an Ed25519 public-key signature (not HMAC, not the Standard Webhooks spec). Two headers are sent:

• telnyx-signature-ed25519 — base64-encoded Ed25519 signature (64 bytes)
• telnyx-timestamp — Unix seconds when the event was signed

The signed message is `${telnyx-timestamp}|${raw_body}` (timestamp, a literal |, then the raw request body — never re-serialized JSON). Verify it with your account's base64 public key from Mission Control → Account Settings → Keys & Credentials → Public Key (per-account, not per-profile). Enforce a timestamp tolerance (5 minutes) to block replays.

SDK note: The telnyx@7 (Node) and telnyx (Python) SDKs expose client.webhooks.unwrap(), but the pinned versions wire it to the Standard Webhooks library, which expects webhook-id / webhook-signature / webhook-timestamp headers — not Telnyx's Ed25519 scheme — so it rejects genuine Telnyx webhooks. Verify manually with a maintained Ed25519 library instead (below). See references/verification.md.

Node (tweetnacl):

const nacl = require('tweetnacl');

function verifyTelnyx(rawBody, signature, timestamp, publicKeyB64) {
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp, 10)) > 300) return false; // replay guard
  const message = Buffer.from(`${timestamp}|${rawBody}`, 'utf8');   // raw body!
  try {
    return nacl.sign.detached.verify(
      new Uint8Array(message),
      new Uint8Array(Buffer.from(signature, 'base64')),
      new Uint8Array(Buffer.from(publicKeyB64, 'base64'))
    );
  } catch { return false; }
}