Skip to content

team-telnyx/ai / providers/claude/plugins/telnyx-platform/skills/telnyx-twilio-migration

telnyx-twilio-migration

Unverified

Migrate from Twilio to Telnyx. Orchestrates a complete 6-phase migration: discovery, planning, setup, code migration, validation, and cleanup. Covers voice (TwiML to TeXML, Call Control API), messaging, WebRTC, SIP trunking, verify, fax, video, IoT, number lookup, and porting. Includes automated scanners, validation scripts, and integration tests.

FileKindSize
SKILL.mdskill md43.3 KB
references/account-setup-guide.mdmarkdown17.8 KB
references/error-code-mapping.mdmarkdown11.0 KB
references/fax-migration.mdmarkdown14.7 KB
references/iot-migration.mdmarkdown17.9 KB
references/lookup-migration.mdmarkdown14.3 KB
references/messaging-migration.mdmarkdown36.5 KB
references/mobile-sdk-migration.mdmarkdown38.6 KB
references/number-porting.mdmarkdown17.0 KB
references/numbers-migration.mdmarkdown21.1 KB
references/product-mapping.mdmarkdown6.7 KB
references/sdk-api-details/10dlc.mdmarkdown9.8 KB
references/sdk-api-details/ai-assistants.mdmarkdown5.8 KB
references/sdk-api-details/messaging.mdmarkdown16.1 KB
references/sdk-api-details/numbers.mdmarkdown10.1 KB
references/sdk-api-details/voice.mdmarkdown9.6 KB
references/sip-trunking-migration.mdmarkdown18.1 KB
references/texml-verbs.mdmarkdown43.7 KB
references/unsupported-products.mdmarkdown3.5 KB
references/verify-migration.mdmarkdown18.4 KB
references/video-migration.mdmarkdown20.6 KB
references/voice-migration.mdmarkdown37.2 KB
references/webhook-migration.mdmarkdown20.3 KB
references/webrtc-migration.mdmarkdown50.0 KB
scripts/lint-telnyx-correctness.shexecutablescript31.4 KB
scripts/migration-state.shexecutablescript7.3 KB
scripts/post-test-diagnostic.shexecutablescript18.9 KB
scripts/preflight-check.shexecutablescript13.4 KB
scripts/run-discovery.shexecutablescript7.7 KB
scripts/run-validation.shexecutablescript13.1 KB
scripts/scan-twilio-deep.pyexecutablescript64.8 KB
scripts/scan-twilio-usage.shexecutablescript29.1 KB
scripts/test-migration/smoke-test.shexecutablescript10.0 KB
scripts/test-migration/test-fax.shexecutablescript8.7 KB
scripts/test-migration/test-lookup.shexecutablescript5.5 KB
scripts/test-migration/test-messaging.shexecutablescript18.8 KB
scripts/test-migration/test-sip.shexecutablescript29.6 KB
scripts/test-migration/test-verify.shexecutablescript13.6 KB
scripts/test-migration/test-voice.shexecutablescript22.4 KB
scripts/test-migration/test-webhooks-local.pyexecutablescript9.7 KB
scripts/test-migration/test-webrtc.shexecutablescript24.0 KB
scripts/test-migration/webhook-receiver.pyexecutablescript11.8 KB
scripts/validate-migration.shexecutablescript31.1 KB
scripts/validate-texml.shexecutablescript61.4 KB
sdk-reference/curl/10dlc.mdmarkdown25.8 KB
sdk-reference/curl/account-access.mdmarkdown15.6 KB
sdk-reference/curl/account-management.mdmarkdown9.5 KB
sdk-reference/curl/account-notifications.mdmarkdown11.0 KB
sdk-reference/curl/account-reports.mdmarkdown45.5 KB
sdk-reference/curl/account.mdmarkdown8.1 KB
sdk-reference/curl/ai-assistants.mdmarkdown34.3 KB
sdk-reference/curl/ai-inference.mdmarkdown34.5 KB
sdk-reference/curl/fax.mdmarkdown19.8 KB
sdk-reference/curl/iot.mdmarkdown49.4 KB
sdk-reference/curl/messaging-hosted.mdmarkdown23.3 KB
sdk-reference/curl/messaging-profiles.mdmarkdown14.2 KB
sdk-reference/curl/messaging.mdmarkdown29.1 KB
sdk-reference/curl/missions.mdmarkdown23.5 KB
sdk-reference/curl/networking.mdmarkdown39.8 KB
sdk-reference/curl/numbers-compliance.mdmarkdown30.2 KB
sdk-reference/curl/numbers-config.mdmarkdown29.7 KB
sdk-reference/curl/numbers-services.mdmarkdown12.6 KB
sdk-reference/curl/numbers.mdmarkdown24.0 KB
sdk-reference/curl/oauth.mdmarkdown15.6 KB
sdk-reference/curl/porting-in.mdmarkdown35.1 KB
sdk-reference/curl/porting-out.mdmarkdown9.8 KB
sdk-reference/curl/sip-integrations.mdmarkdown27.5 KB
sdk-reference/curl/sip.mdmarkdown47.6 KB
sdk-reference/curl/storage.mdmarkdown4.2 KB
sdk-reference/curl/texml.mdmarkdown31.4 KB
sdk-reference/curl/verify.mdmarkdown13.2 KB
sdk-reference/curl/video.mdmarkdown17.2 KB
sdk-reference/curl/voice-advanced.mdmarkdown32.8 KB
sdk-reference/curl/voice-conferencing.mdmarkdown41.6 KB
sdk-reference/curl/voice-gather.mdmarkdown14.7 KB
sdk-reference/curl/voice-media.mdmarkdown17.8 KB
sdk-reference/curl/voice-streaming.mdmarkdown13.3 KB
sdk-reference/curl/voice.mdmarkdown37.6 KB
sdk-reference/curl/webrtc.mdmarkdown6.5 KB
sdk-reference/go/10dlc.mdmarkdown29.0 KB
sdk-reference/go/account-access.mdmarkdown17.0 KB
sdk-reference/go/account-management.mdmarkdown9.9 KB
sdk-reference/go/account-notifications.mdmarkdown12.4 KB
sdk-reference/go/account-reports.mdmarkdown31.5 KB
sdk-reference/go/account.mdmarkdown9.1 KB
sdk-reference/go/ai-assistants.mdmarkdown37.7 KB
sdk-reference/go/ai-inference.mdmarkdown27.1 KB
sdk-reference/go/fax.mdmarkdown20.2 KB
sdk-reference/go/iot.mdmarkdown51.3 KB
sdk-reference/go/messaging-hosted.mdmarkdown24.5 KB
sdk-reference/go/messaging-profiles.mdmarkdown15.2 KB
sdk-reference/go/messaging.mdmarkdown30.1 KB
sdk-reference/go/missions.mdmarkdown26.9 KB
sdk-reference/go/networking.mdmarkdown42.5 KB
sdk-reference/go/numbers-compliance.mdmarkdown28.2 KB
sdk-reference/go/numbers-config.mdmarkdown29.5 KB
sdk-reference/go/numbers-services.mdmarkdown14.1 KB
sdk-reference/go/numbers.mdmarkdown26.7 KB
sdk-reference/go/oauth.mdmarkdown11.7 KB
sdk-reference/go/porting-in.mdmarkdown41.1 KB
sdk-reference/go/porting-out.mdmarkdown10.9 KB
sdk-reference/go/sip-integrations.mdmarkdown32.3 KB
sdk-reference/go/sip.mdmarkdown49.1 KB
sdk-reference/go/storage.mdmarkdown4.8 KB
sdk-reference/go/texml.mdmarkdown35.7 KB
sdk-reference/go/verify.mdmarkdown14.4 KB
sdk-reference/go/video.mdmarkdown18.6 KB
sdk-reference/go/voice-advanced.mdmarkdown33.2 KB
sdk-reference/go/voice-conferencing.mdmarkdown42.3 KB
sdk-reference/go/voice-gather.mdmarkdown14.5 KB
sdk-reference/go/voice-media.mdmarkdown18.1 KB
sdk-reference/go/voice-streaming.mdmarkdown13.5 KB
sdk-reference/go/voice.mdmarkdown39.2 KB
sdk-reference/go/webrtc.mdmarkdown7.5 KB
sdk-reference/java/10dlc.mdmarkdown31.3 KB
sdk-reference/java/account-access.mdmarkdown18.5 KB
sdk-reference/java/account-management.mdmarkdown11.1 KB
sdk-reference/java/account-notifications.mdmarkdown14.3 KB
sdk-reference/java/account-reports.mdmarkdown36.5 KB
sdk-reference/java/account.mdmarkdown10.3 KB
sdk-reference/java/ai-assistants.mdmarkdown39.2 KB
sdk-reference/java/ai-inference.mdmarkdown30.7 KB
sdk-reference/java/fax.mdmarkdown21.5 KB
sdk-reference/java/iot.mdmarkdown57.5 KB
sdk-reference/java/messaging-hosted.mdmarkdown28.4 KB
sdk-reference/java/messaging-profiles.mdmarkdown15.7 KB
sdk-reference/java/messaging.mdmarkdown32.2 KB
sdk-reference/java/missions.mdmarkdown31.6 KB
sdk-reference/java/networking.mdmarkdown47.1 KB
sdk-reference/java/numbers-compliance.mdmarkdown31.1 KB
sdk-reference/java/numbers-config.mdmarkdown32.2 KB
sdk-reference/java/numbers-services.mdmarkdown15.9 KB
sdk-reference/java/numbers.mdmarkdown28.4 KB
sdk-reference/java/oauth.mdmarkdown13.0 KB
sdk-reference/java/porting-in.mdmarkdown46.2 KB
sdk-reference/java/porting-out.mdmarkdown11.9 KB
sdk-reference/java/sip-integrations.mdmarkdown38.1 KB
sdk-reference/java/sip.mdmarkdown51.9 KB
sdk-reference/java/storage.mdmarkdown5.7 KB
sdk-reference/java/texml.mdmarkdown41.3 KB
sdk-reference/java/verify.mdmarkdown16.0 KB
sdk-reference/java/video.mdmarkdown20.3 KB
sdk-reference/java/voice-advanced.mdmarkdown35.0 KB
sdk-reference/java/voice-conferencing.mdmarkdown46.0 KB
sdk-reference/java/voice-gather.mdmarkdown16.1 KB
sdk-reference/java/voice-media.mdmarkdown19.5 KB
sdk-reference/java/voice-streaming.mdmarkdown14.7 KB
sdk-reference/java/voice.mdmarkdown40.8 KB
sdk-reference/java/webrtc.mdmarkdown8.5 KB
sdk-reference/javascript/10dlc.mdmarkdown28.5 KB
sdk-reference/javascript/account-access.mdmarkdown15.9 KB
sdk-reference/javascript/account-management.mdmarkdown9.6 KB
sdk-reference/javascript/account-notifications.mdmarkdown11.7 KB
sdk-reference/javascript/account-reports.mdmarkdown29.3 KB
sdk-reference/javascript/account.mdmarkdown8.7 KB
sdk-reference/javascript/ai-assistants.mdmarkdown37.5 KB
sdk-reference/javascript/ai-inference.mdmarkdown24.4 KB
sdk-reference/javascript/fax.mdmarkdown19.9 KB
sdk-reference/javascript/iot.mdmarkdown47.4 KB
sdk-reference/javascript/messaging-hosted.mdmarkdown22.4 KB
sdk-reference/javascript/messaging-profiles.mdmarkdown14.8 KB
sdk-reference/javascript/messaging.mdmarkdown29.7 KB
sdk-reference/javascript/missions.mdmarkdown23.8 KB
sdk-reference/javascript/networking.mdmarkdown39.3 KB
sdk-reference/javascript/numbers-compliance.mdmarkdown25.9 KB
sdk-reference/javascript/numbers-config.mdmarkdown28.3 KB
sdk-reference/javascript/numbers-services.mdmarkdown13.0 KB
sdk-reference/javascript/numbers.mdmarkdown26.1 KB
sdk-reference/javascript/oauth.mdmarkdown10.8 KB
sdk-reference/javascript/porting-in.mdmarkdown37.4 KB
sdk-reference/javascript/porting-out.mdmarkdown10.2 KB
sdk-reference/javascript/sip-integrations.mdmarkdown28.5 KB
sdk-reference/javascript/sip.mdmarkdown47.4 KB
sdk-reference/javascript/storage.mdmarkdown4.5 KB
sdk-reference/javascript/texml.mdmarkdown31.9 KB
sdk-reference/javascript/verify.mdmarkdown13.3 KB
sdk-reference/javascript/video.mdmarkdown17.2 KB
sdk-reference/javascript/voice-advanced.mdmarkdown32.6 KB
sdk-reference/javascript/voice-conferencing.mdmarkdown40.4 KB
sdk-reference/javascript/voice-gather.mdmarkdown14.3 KB
sdk-reference/javascript/voice-media.mdmarkdown17.8 KB
sdk-reference/javascript/voice-streaming.mdmarkdown13.4 KB
sdk-reference/javascript/voice.mdmarkdown39.4 KB
sdk-reference/javascript/webrtc.mdmarkdown7.2 KB
sdk-reference/python/10dlc.mdmarkdown28.5 KB
sdk-reference/python/account-access.mdmarkdown15.0 KB
sdk-reference/python/account-management.mdmarkdown9.1 KB
sdk-reference/python/account-notifications.mdmarkdown10.9 KB
sdk-reference/python/account-reports.mdmarkdown28.1 KB
sdk-reference/python/account.mdmarkdown8.1 KB
sdk-reference/python/ai-assistants.mdmarkdown37.3 KB
sdk-reference/python/ai-inference.mdmarkdown23.4 KB
sdk-reference/python/fax.mdmarkdown19.5 KB
sdk-reference/python/iot.mdmarkdown45.3 KB
sdk-reference/python/messaging-hosted.mdmarkdown21.7 KB
sdk-reference/python/messaging-profiles.mdmarkdown14.1 KB
sdk-reference/python/messaging.mdmarkdown29.4 KB
sdk-reference/python/missions.mdmarkdown23.2 KB
sdk-reference/python/networking.mdmarkdown37.1 KB
sdk-reference/python/numbers-compliance.mdmarkdown24.6 KB

references/webhook-migration.md

View on GitHub
# Webhook Migration: Twilio to Telnyx

Comprehensive guide for migrating webhook handlers from Twilio to Telnyx. Messaging and Call Control use Telnyx's nested JSON event structure; TeXML callbacks remain Twilio-style form data.

## Payload Structure

**Twilio** sends flat form-encoded key-value pairs (`application/x-www-form-urlencoded`):
```
MessageSid=SM123&From=%2B15551234567&To=%2B15559876543&Body=Hello
```

**Telnyx Messaging and Call Control** send nested JSON (`application/json`):
```json
{
  "data": {
    "event_type": "message.received",
    "id": "evt_abc123",
    "occurred_at": "2026-01-15T12:00:00Z",
    "payload": {
      "id": "msg_xyz789",
      "from": {"phone_number": "+15551234567"},
      "to": [{"phone_number": "+15559876543"}],
      "text": "Hello"
    }
  }
}
```

**Key change for Messaging and Call Control**: parse the JSON body and access fields via `data.payload.*` instead of flat keys. Do not apply this rule to TeXML callbacks, which use `application/x-www-form-urlencoded` and flat Twilio-style fields.

## Messaging Webhook Field Mapping

### Inbound Message (`message.received`)

| Twilio Field | Telnyx Field | Access Path |
|---|---|---|
| `MessageSid` | `id` | `data.payload.id` |
| `From` | `from.phone_number` | `data.payload.from.phone_number` |
| `To` | `to[0].phone_number` | `data.payload.to[0].phone_number` |
| `Body` | `text` | `data.payload.text` |
| `NumMedia` | `media.length` | `data.payload.media` (array length) |
| `MediaUrl0` | `media[0].url` | `data.payload.media[0].url` |
| `MediaContentType0` | `media[0].content_type` | `data.payload.media[0].content_type` |
| `AccountSid` | N/A | Not included |
| `ApiVersion` | N/A | Not included |

### Delivery Status (`message.sent`, `message.finalized`)

Telnyx emits only two outbound delivery events: an intermediate `message.sent` and a terminal `message.finalized`. There is **no** `message.queued`, `message.delivered`, or `message.failed` event. The actual per-recipient outcome lives in `data.payload.to[0].status`, not in the event type.

| Twilio Field | Telnyx Field | Access Path |
|---|---|---|
| `MessageStatus` | `event_type` + `to[].status` | `data.event_type` (`message.sent` / `message.finalized`) plus `data.payload.to[0].status` |
| `MessageSid` | `id` | `data.payload.id` |
| `ErrorCode` | `errors[0].code` | `data.payload.errors[0].code` |
| `ErrorMessage` | `errors[0].title` | `data.payload.errors[0].title` |

### Messaging Status Value Mapping

Telnyx event types do not carry the delivery outcome; read it from `data.payload.to[0].status` on a `message.finalized` event.

| Twilio Status | Telnyx Event Type | Per-recipient `to[0].status` | Notes |
|---|---|---|---|
| `queued` | (none — accepted in the API response) | — | Send request accepted synchronously; no dedicated webhook |
| `sent` | `message.sent` | — | Handed to carrier (intermediate event) |
| `delivered` | `message.finalized` | `delivered` | Carrier confirmed delivery |
| `undelivered` | `message.finalized` | `delivery_failed` | Reached carrier but not delivered (check `errors`) |
| `failed` | `message.finalized` | `sending_failed` | Never handed to carrier (check `errors`) |
| `received` | `message.received` | — | Inbound message |

## Voice Webhook Field Mapping

### TeXML Callbacks (form-encoded, similar to Twilio)

TeXML callbacks use form-encoded params similar to Twilio, so the migration is simpler:

| Twilio Field | Telnyx Field | Notes |
|---|---|---|
| `CallSid` | `CallSid` | Telnyx call control ID |
| `AccountSid` | `AccountSid` | Telnyx account `user_id` |
| N/A | `ConnectionId` | Telnyx connection ID |
| `SequenceNumber` | `SequenceNumber` | Present on TeXML call-progress callbacks; pair with `CallSid` to order callbacks and deduplicate redeliveries |
| `From` | `From` | Caller number |
| `To` | `To` | Called number |
| `CallStatus` | `CallStatus` | Same Twilio-style values: `queued`, `initiated`, `ringing`, `in-progress`, `completed`, `busy`, `no-answer`, `failed`, `canceled`. Note the answered state is `in-progress` — TeXML does **not** use `answered` (that is a Call Control JSON event name, `call.answered`) |
| `Direction` | `Direction` | `inbound` or `outbound` |
| `RecordingUrl` | `RecordingUrl` | **Expires after 10 minutes** — download promptly |

`SequenceNumber` is a call-progress callback field (for example, initiated,
ringing, answered, and completed), not a guarantee for every TeXML callback.
Use the pair (`CallSid`, `SequenceNumber`) when ordering or deduplicating those
call-progress events.

### Call Control Webhooks (JSON)

| Twilio Field | Telnyx Event | Access Path |
|---|---|---|
| `CallSid` | `call_control_id` | `data.payload.call_control_id` |
| `From` | `from` | `data.payload.from` |
| `To` | `to` | `data.payload.to` |
| `CallStatus=initiated` | `call.initiated` | `data.event_type` |
| `CallStatus=ringing` | `call.ringing` | `data.event_type` |
| `CallStatus=in-progress` | `call.answered` | `data.event_type` |
| `CallStatus=completed` | `call.hangup` | `data.event_type` |

### Voice Status Value Mapping

| Twilio CallStatus | Telnyx Event | Notes |
|---|---|---|
| `initiated` | `call.initiated` | Call created |
| `ringing` | `call.ringing` | Remote party ringing |
| `in-progress` | `call.answered` | Call connected (TeXML/Twilio use `in-progress`; Call Control JSON uses the `call.answered` event) |
| `completed` | `call.hangup` | Call ended normally |
| `busy` | `call.hangup` (cause: `user_busy`) | Remote busy |
| `no-answer` | `call.hangup` (cause: `timeout`) | No answer |
| `failed` | `call.hangup` (cause: varies, e.g. `call_rejected`) | Call failed |
| `canceled` | `call.hangup` (cause: `originator_cancel`) | Caller hung up |

## Signature Verification

### Twilio (HMAC-SHA1) — Remove This

```python
from twilio.request_validator import RequestValidator
validator = RequestValidator(auth_token)
is_valid = validator.validate(url, params, request.headers.get('X-Twilio-Signature'))
```

### Telnyx (Ed25519) — Add This

**Python:**
```python
from telnyx import Telnyx
client = Telnyx(api_key="YOUR_API_KEY", public_key="YOUR_PUBLIC_KEY")

# Verify + parse webhook in one step — raises TelnyxWebhookVerificationError on failure
event = client.webhooks.unwrap(
    request.data.decode("utf-8"),
    headers=request.headers,  # must contain telnyx-signature-ed25519 and telnyx-timestamp
)
```

**Node.js:**
```javascript
const Telnyx = require('telnyx');
const client = new Telnyx({ apiKey: 'YOUR_API_KEY' });

// Verify + parse webhook — throws on invalid signature
const event = await client.webhooks.unwrap(
  req.rawBody,  // Must be original bytes — see Express example below for rawBody setup
  { headers: req.headers, key: 'YOUR_PUBLIC_KEY' }
);
```

**Go (manual Ed25519):**
```go
import (
    "crypto/ed25519"
    "encoding/base64"
)

func verifyWebhook(payload, signature, timestamp, publicKeyBase64 string) bool {
    pubKey, _ := base64.StdEncoding.DecodeString(publicKeyBase64)
    sig, _ := base64.StdEncoding.DecodeString(signature)
    message := []byte(timestamp + "|" + payload)
    return ed25519.Verify(ed25519.PublicKey(pubKey), message, sig)
}
```

**Ruby:**
```ruby
require 'telnyx'
client = Telnyx::Client.new(api_key: 'YOUR_API_KEY')
# Verification lives on the CLIENT: client.webhooks.unwrap(payload, headers:).
# There is no Telnyx::Webhook module - referencing one raises NameError, and
# because NameError is a StandardError the usual `rescue StandardError` around
# it swallows the error and rejects EVERY webhook with 403.
client.webhooks.unwrap(payload, headers: telnyx_headers, key: ENV['TELNYX_PUBLIC_KEY'])
```

## Framework-Specific Examples

### Flask (Python)

```python
from flask import Flask, request, jsonify
from telnyx import Telnyx

app = Flask(__name__)
client = Telnyx(api_key="YOUR_API_KEY", public_key="YOUR_PUBLIC_KEY")

@app.route('/webhooks/messaging', methods=['POST'])
def messaging_webhook():
    # Verify signature + parse event in one step
    try:
        event = client.webhooks.unwrap(
            request.data.decode("utf-8"),
            headers=request.headers,
        )
    except Exception:
        return "Forbidden", 403

    event_data = request.json['data']
    event_type = event_data['event_type']
    payload = event_data['payload']

    if event_type == 'message.received':
        from_number = payload['from']['phone_number']
        text = payload['text']
        # Process inbound message...
    elif event_type == 'message.sent':
        # Intermediate event — message handed to the carrier
        msg_id = payload['id']
    elif event_type == 'message.finalized':
        # Terminal event — read the per-recipient outcome from to[0].status
        status = payload['to'][0]['status']  # delivered | delivery_failed | sending_failed
        if status == 'delivered':
            pass  # Handle delivery confirmation...
        else:
            errors = payload.get('errors', [])
            # Handle failure (delivery_failed / sending_failed)...

    return jsonify({"status": "ok"}), 200
```

### Express (Node.js)

**Important**: Signature verification requires the raw request body (original bytes), not re-serialized JSON. Use the `verify` callback on `express.json()` to capture raw bytes.

```javascript
const express = require('express');
const Telnyx = require('telnyx');
const client = new Telnyx({ apiKey: 'YOUR_API_KEY' });
const app = express();

// Capture raw body for webhook signature verification
app.use(express.json({
  verify: (req, res, buf) => { req.rawBody = buf.toString('utf-8'); }
}));

app.post('/webhooks/messaging', async (req, res) => {
  // Verify signature + parse event using raw body (NOT JSON.stringify(req.body))
  try {
    const event = await client.webhooks.unwrap(
      req.rawBody,  // Must be the original bytes, not re-serialized
      { headers: req.headers, key: 'YOUR_PUBLIC_KEY' }
    );
  } catch (e) {
    return res.status(403).send('Forbidden');
  }

  const { event_type, payload } = req.body.data;

  if (event_type === 'message.received') {
    const from = payload.from.phone_number;
    const text = payload.text;
    // Process inbound message...
  } else if (event_type === 'message.sent') {
    // Intermediate event — message handed to the carrier
  } else if (event_type === 'message.finalized') {
    // Terminal event — read the per-recipient outcome from to[0].status
    const status = payload.to[0].status; // delivered | delivery_failed | sending_failed
    if (status === 'delivered') {
      // Handle delivery confirmation...
    } else {
      const errors = payload.errors || [];
      // Handle failure (delivery_failed / sending_failed)...
    }
  }

  res.sendStatus(200);
});
```

### Sinatra (Ruby)

```ruby
require 'sinatra'
require 'json'
require 'telnyx'

set :port, 5000
client = Telnyx::Client.new(api_key: ENV.fetch('TELNYX_API_KEY'))

post '/webhooks/messaging' do
  payload = request.body.read
  telnyx_headers = {
    'telnyx-signature-ed25519' => request.env['HTTP_TELNYX_SIGNATURE_ED25519'],
    'telnyx-timestamp'         => request.env['HTTP_TELNYX_TIMESTAMP']
  }

  # Verify signature
  begin
    client.webhooks.unwrap(
      payload,
      headers: telnyx_headers,
      key: ENV['TELNYX_PUBLIC_KEY']
    )
  rescue StandardError
    halt 403, 'Forbidden'
  end

  event = JSON.parse(payload)
  event_type = event.dig('data', 'event_type')
  data = event.dig('data', 'payload')

  case event_type
  when 'message.received'
    from_number = data.dig('from', 'phone_number')
    text = data['text']
    # Process inbound message...
  when 'message.sent'
    # Intermediate event — message handed to the carrier
  when 'message.finalized'
    # Terminal event — read the per-recipient outcome from to[0].status
    status = data['to'][0]['status'] # delivered | delivery_failed | sending_failed
    if status == 'delivered'
      # Handle delivery confirmation...
    else
      errors = data['errors'] || []
      # Handle failure (delivery_failed / sending_failed)...
    end
  end

  content_type :json
  { status: 'ok' }.to_json
end
```

### Rails (Ruby on Rails)

**Important**: Rails controllers need `skip_before_action :verify_authenticity_token` since Telnyx webhooks don't include CSRF tokens. If the original code used `twilio.webhook()` or Twilio's `RequestValidator` in a `before_action`, replace it with Ed25519 verification — do NOT just remove it.

```ruby
# app/controllers/webhooks_controller.rb
class WebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token

  before_action :verify_telnyx_signature

  def messaging
    event_type = params.dig('data', 'event_type')
    payload = params.dig('data', 'payload')

    case event_type
    when 'message.received'
      from_number = payload.dig('from', 'phone_number')
      text = payload['text']
      # Process inbound message...
    when 'message.sent'
      # Intermediate event — message handed to the carrier
    when 'message.finalized'
      # Terminal event — read the per-recipient outcome from to[0].status
      status = payload.dig('to', 0, 'status') # delivered | delivery_failed | sending_failed
      if status == 'delivered'
        # Handle delivery confirmation...
      else
        errors = payload['errors'] || []
        # Handle failure (delivery_failed / sending_failed)...
      end
    end

    render json: { status: 'ok' }
  end

  def voice
    event_type = params.dig('data', 'event_type')
    payload = params.dig('data', 'payload')

    case event_type
    when 'call.initiated'
      call_control_id = payload['call_control_id']
      # Handle call event...
    when 'call.answered'
      # Handle answered...
    when 'call.hangup'
      # Handle hangup...
    end

    render json: { status: 'ok' }
  end

  private

  def verify_telnyx_signature
    payload = request.body.read
    client = Telnyx::Client.new(api_key: ENV.fetch('TELNYX_API_KEY'))
    signature = request.headers['HTTP_TELNYX_SIGNATURE_ED25519'] ||
                request.headers['telnyx-signature-ed25519']
    timestamp = request.headers['HTTP_TELNYX_TIMESTAMP'] ||
                request.headers['telnyx-timestamp']

    begin
      # unwrap is (payload, headers:, key:) - the signature and timestamp go
      # in the HEADERS hash under their WIRE names. Passing them positionally
      # raises ArgumentError on every request, and `rescue StandardError`
      # below would swallow it and 403 every genuine webhook.
      client.webhooks.unwrap(
        payload,
        headers: {
          'telnyx-signature-ed25519' => signature,
          'telnyx-timestamp'         => timestamp
        },
        key: ENV['TELNYX_PUBLIC_KEY']
      )
    rescue StandardError => e
      Rails.logger.warn "Webhook signature verification failed: #{e.message}"
      head :forbidden
    end
  end
end
```

```ruby
# config/routes.rb
Rails.application.routes.draw do
  post '/webhooks/messaging', to: 'webhooks#messaging'
  post '/webhooks/voice', to: 'webhooks#voice'
end
```

**Rails note**: Use `request.body.read` for signature verification (raw bytes), not `params` (which is parsed). Access Telnyx webhook headers via `request.headers` — Rails may prefix with `HTTP_` and uppercase them (`HTTP_TELNYX_SIGNATURE_ED25519`), so check both forms.

### Go (net/http)

```go
package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

type TelnyxEvent struct {
	Data struct {
		EventType string `json:"event_type"`
		Payload   struct {
			ID   string `json:"id"`
			From struct {
				PhoneNumber string `json:"phone_number"`
			} `json:"from"`
			To []struct {
				PhoneNumber string `json:"phone_number"`
				Status      string `json:"status"`
			} `json:"to"`
			Text   string `json:"text"`
			Errors []struct {
				Code  string `json:"code"`
				Title string `json:"title"`
			} `json:"errors"`
		} `json:"payload"`
	} `json:"data"`
}

func messagingWebhook(w http.ResponseWriter, r *http.Request) {
	body, _ := io.ReadAll(r.Body)

	// Verify Ed25519 signature (see Signature Verification section above)

	var event TelnyxEvent
	if err := json.Unmarshal(body, &event); err != nil {
		http.Error(w, "Bad request", 400)
		return
	}

	switch event.Data.EventType {
	case "message.received":
		from := event.Data.Payload.From.PhoneNumber
		text := event.Data.Payload.Text
		fmt.Printf("SMS from %s: %s\n", from, text)
	case "message.sent":
		// Intermediate event — message handed to the carrier
	case "message.finalized":
		// Terminal event — read the per-recipient outcome from to[0].status
		if len(event.Data.Payload.To) > 0 {
			status := event.Data.Payload.To[0].Status // delivered | delivery_failed | sending_failed
			if status != "delivered" {
				// Handle failure (delivery_failed / sending_failed)...
			}
		}
	}

	w.WriteHeader(200)
	json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
}

func main() {
	http.HandleFunc("/webhooks/messaging", messagingWebhook)
	http.ListenAndServe(":5000", nil)
}
```

## Common Webhook Migration Mistakes

1. **Using the wrong parser for the product** — Messaging and Call Control send JSON, while TeXML callbacks are form-encoded. Use a JSON parser for the former and `request.form` / URL-encoded middleware for TeXML.

2. **Missing `data` wrapper** — Telnyx nests everything under `data`. The event type is at `data.event_type`, not at the top level.

3. **Flat vs nested `from`** — Twilio: `From` is a string. Telnyx: `from` is an object with `phone_number` (and optionally `carrier`, `line_type`).

4. **`to` is an array** — Telnyx `to` is always an array (supports group messaging). Use `to[0].phone_number` for the primary recipient.

5. **No `200 OK` response** — Telnyx expects a `200` response within the timeout. If your handler doesn't respond, Telnyx retries (up to the configured retry count).

6. **Signature header names** — Twilio: `X-Twilio-Signature`. Telnyx: `telnyx-signature-ed25519` + `telnyx-timestamp` (two headers).

7. **Recording URLs expire** — Telnyx voice recording URLs expire after 10 minutes. Download or store them immediately in the webhook handler.

8. **Express raw body for signature verification** — Do NOT use `JSON.stringify(req.body)` — re-serialization changes key order/whitespace and breaks signature verification. Capture the raw body via `express.json({ verify: (req, res, buf) => { req.rawBody = buf.toString('utf-8'); } })` and pass `req.rawBody` to the verification function.

## Django Webhook Handler

Django requires `@csrf_exempt` since Telnyx webhooks won't include CSRF tokens.

```python
# views.py
import json
from telnyx import Telnyx
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_POST
from django.conf import settings

client = Telnyx(api_key=settings.TELNYX_API_KEY, public_key=settings.TELNYX_PUBLIC_KEY)

@csrf_exempt
@require_POST
def telnyx_webhook(request):
    # Verify signature + parse event
    try:
        client.webhooks.unwrap(
            request.body.decode('utf-8'),  # raw body string
            headers={
                'telnyx-signature-ed25519': request.META.get('HTTP_TELNYX_SIGNATURE_ED25519', ''),
                'telnyx-timestamp': request.META.get('HTTP_TELNYX_TIMESTAMP', ''),
            },
        )
    except Exception:
        return JsonResponse({'error': 'Invalid signature'}, status=403)

    data = json.loads(request.body)
    event_type = data['data']['event_type']
    payload = data['data']['payload']

    if event_type == 'message.received':
        from_number = payload['from']['phone_number']
        text = payload.get('text', '')
        # Handle inbound message
    elif event_type == 'message.sent':
        # Intermediate event — message handed to the carrier
        pass
    elif event_type == 'message.finalized':
        # Terminal event — read the per-recipient outcome from to[0].status
        status = payload['to'][0]['status']  # delivered | delivery_failed | sending_failed
        if status != 'delivered':
            errors = payload.get('errors', [])
            # Handle failure (delivery_failed / sending_failed)...
    elif event_type == 'call.initiated':
        call_control_id = payload['call_control_id']
        # Handle call event

    return JsonResponse({'status': 'ok'})
```

```python
# urls.py
from django.urls import path
from . import views

urlpatterns = [
    path('webhooks/telnyx/', views.telnyx_webhook, name='telnyx_webhook'),
]
```

**Django note**: Use `request.body` (bytes) for signature verification — not `request.POST` which is form-parsed. Telnyx webhook headers arrive as `HTTP_TELNYX_SIGNATURE_ED25519` in Django's `request.META` (Django uppercases and prefixes `HTTP_`).
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall