The `call.initiated` webhook is incorrectly mapped to `NumberOrderStatusUpdate` or `CallAIGatherEndedWebhookEvent`, instead of the expected `CallInitiatedWebhookEvent`.

[iwangpeng]

A small portion of call.initiated webhooks have this issue. Related call_control_id: v3:EGaHosgKDqqWmnMNj0Z-5Z2iSJNkgWr9_Bk8KKrsn4mKNYtD_hHkpA

When testing with the same webhook data at different times, two different results were observed, both incorrect:

• Tests before UTC 2026-05-15T04:00:00+0000 mapped to NumberOrderStatusUpdate
• Tests after that time mapped to CallAIGatherEndedWebhookEvent
  (It is uncertain whether the issue is actually time-dependent.)

Tested versions: v4.133.0 (latest), v4.122.0, v4.116.0

Test code:

import telnyx
from django.conf import settings

telnyx_client = telnyx.Telnyx(api_key=settings.TELNYX_API_KEY, public_key=settings.TELNYX_PUBLIC_KEY)

data = '''{
  "created_at": "2026-05-14T23:21:06.640595Z",
  "event_type": "call.initiated",
  "payload": {
    "call_control_id": "v3:EGaHosgKDqqWmnMNj0Z-5Z2iSJNkgWr9_Bk8KKrsn4mKNYtD_hHkpA",
    "call_leg_id": "94839524-4feb-11f1-ab3d-02420aef951f",
    "call_session_id": "94838a52-4feb-11f1-bf82-02420aef951f",
    "caller_id_name": "+11111111111",
    "calling_party_type": "pstn",
    "client_state": null,
    "connection_codecs": "G722,PCMA,PCMU,VP8,H264",
    "connection_id": "1111111111111111111",
    "custom_headers": [
      {
        "name": "P-Asserted-Service",
        "value": "urn:urn-7:3gpp-service.ims.icsi.mmtel"
      },
      {
        "name": "P-Early-Media",
        "value": "supported"
      }
    ],
    "direction": "incoming",
    "from": "+11111111111",
    "from_sip_uri": "+11111111111@1.1.1.1",
    "occurred_at": "2026-05-14T23:21:05.251813Z",
    "offered_codecs": "AMR-WB~OCTET-ALIGN=0; MODE-SET=0,16000H,AMR-WB~OCTET-ALIGN=1; MODE-SET=0,16000H,PCMU",
    "sip_headers": [
      {
        "name": "Diversion",
        "value": "<sip:+11111111111@msg.pc.t-mobile.com;user=phone;enum=yes?Reason=SIP%3Bcause%3D302>;reason=unconditional;counter=1;privacy=off"
      }
    ],
    "start_time": "2026-05-14T23:21:05.251813Z",
    "state": "parked",
    "to": "+11111111111",
    "to_sip_uri": "+11111111111@1.1.1.1"
  },
  "record_type": "event",
  "webhook_id": "ea47dada-c255-40e6-b91b-2a9a8904c9c5"
}'''

event = telnyx_client.webhooks.unsafe_unwrap(data)
print(type(event))

[kangyue92]

Same issue

Summary

client.webhooks.unsafe_unwrap() (and unwrap()) returns an event whose .data.payload is resolved to the wrong type. For a call.initiated webhook, event.data.payload comes back as NumberOrderWithPhoneNumbers (or even a plain dict) instead of call_initiated.Payload, so accessing documented fields like payload.from_ raises:

AttributeError: 'NumberOrderWithPhoneNumbers' object has no attribute 'from_'

Root cause

UnsafeUnwrapWebhookEvent / UnwrapWebhookEvent are plain typing.Unions of 77 variants, with no discriminator:

# src/telnyx/types/unsafe_unwrap_webhook_event.py
UnsafeUnwrapWebhookEvent: TypeAlias = Union[
    CallAIGatherEndedWebhookEvent,
    ...
    TranscriptionWebhookEvent,
]

unsafe_unwrap feeds the parsed JSON into construct_type(type_=UnsafeUnwrapWebhookEvent, ...). Because the union is non-discriminated and many payload variants have all-Optional fields (e.g. NumberOrderWithPhoneNumbers), construct_type's best-effort matching selects the wrong member — especially for "rich" payloads with many fields. The event already carries an unambiguous discriminator at data.event_type (a Literal, e.g. "call.initiated"), but it isn't used for resolution.

Reproduction

from telnyx._models import construct_type
from telnyx.types.unsafe_unwrap_webhook_event import UnsafeUnwrapWebhookEvent

body = {"data": {
    "event_type": "call.initiated",
    "id": "5f8e030e-d0d1-4868-b101-aaaea6ff8e93",
    "occurred_at": "2026-06-03T00:56:15.744181Z",
    "record_type": "event",
    "payload": {
        "call_control_id": "v3:abc",
        "call_leg_id": "0614813a-5ee7-11f1-a13a-02420aef961f",
        "call_session_id": "0614773a-5ee7-11f1-b784-02420aef961f",
        "caller_id_name": "+18445964978",
        "calling_party_type": "pstn",
        "connection_codecs": "G722,PCMA,PCMU,VP8,H264",
        "connection_id": "2929820585485666183",
        "direction": "incoming",
        "from": "+18445964978",
        "from_sip_uri": "+18445964978@152.189.49.238:5060",
        "offered_codecs": "PCMU",
        "sip_headers": [{"name": "Diversion", "value": "<sip:+18703312253>"}],
        "start_time": "2026-06-03T00:56:15.744181Z",
        "state": "parked",
        "to": "+18704102244",
        "to_sip_uri": "8703312253@192.76.120.9:5060",
    },
}}

ev = construct_type(type_=UnsafeUnwrapWebhookEvent, value=body)
print(type(ev.data.payload).__name__)        # -> 'dict' (or 'NumberOrderWithPhoneNumbers'), expected 'Payload'
print(hasattr(ev.data.payload, "from_"))      # -> False, expected True

Re-constructing with the concrete type resolves correctly, confirming the data is valid and only the union resolution is at fault:

from telnyx.types.call_initiated_webhook_event import CallInitiatedWebhookEvent
fixed = construct_type(type_=CallInitiatedWebhookEvent, value=body)
print(fixed.data.payload.from_)               # -> '+18445964978'

Expected

event.data.payload should resolve to the variant indicated by data.event_type, so payload.from_ (and other variant-specific fields) work as documented.

Suggested fix

Make the webhook unions discriminated on data.event_type, e.g.:

UnsafeUnwrapWebhookEvent: TypeAlias = Annotated[
    Union[...],
    PropertyInfo(discriminator="...")  # keyed off data.event_type
]

(The same applies to UnwrapWebhookEvent.) This is a known pain point — the messaging side has the identical symptom: inbound MMS resolves to NumberOrderWithPhoneNumbers instead of InboundMessagePayload.

Environment

• telnyx 4.133.0 (also confirmed the union is still non-discriminated on the v4.147.0 tag, so latest is affected too)
• Python 3.13