Node.js 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(). Verification needs the exact bytes Telnyx sent, so read the body as text rather than letting the framework parse it first:

import express from "express";
import Telnyx from "telnyx";

const client = new Telnyx(); // reads TELNYX_API_KEY and TELNYX_PUBLIC_KEY

const app = express();

app.post(
  "/webhooks/telnyx",
  express.text({ type: "application/json" }),
  (req, res) => {
    try {
      const event = client.webhooks.unwrap(req.body, {
        headers: req.headers as Record<string, string>,
      });
      console.log(event.data?.event_type);
      res.sendStatus(200);
    } catch {
      res.sendStatus(400); // signature invalid or payload malformed
    }
  },
);

app.listen(3000);

unwrap() throws when the signature does not match, and returns the parsed event as a typed union of every webhook event the API sends — narrow on event.data?.event_type to handle specific events.

Skipping verification

client.webhooks.unsafeUnwrap(body) 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

Node.js 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