Telnyx webhook verify() crashes in ESM: the tweetnacl import fix

TL;DR

For "TypeError: Cannot read properties of undefined (reading 'detached')": upgrade to a version with the crypto.subtle-based verifier. Note the migration cost the maintainers called out: verify() and unwrap() became async with that change, so await them or your verification will silently not run.

TypeError: Cannot read properties of undefined (reading 'detached')

Steps

1. When Telnyx webhook verification throws a detached/undefined error in an ESM project, it is the SDK's tweetnacl import, not your code. Upgrade to a version with the crypto.subtle-based verifier. Note the migration cost the maintainers called out: verify() and unwrap() became async with that change, so await them or your verification will silently not run.

When to use

You are seeing this: When Telnyx webhook verification throws a detached/undefined error in an ESM project, it is the SDK's tweetnacl import, not your code. Use this skill when you run into "Telnyx webhook verify() crashes in ESM: the tweetnacl import fix".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Edge cases

• Note the migration cost the maintainers called out: verify() and unwrap() became async with that change, so await them or your verification will silently not run.

Source: GitHub issue team-telnyx/telnyx-node#302: Calling TelnyxWebhook.verify() in an ESM project threw "TypeError: Cannot read properties of undefined (reading 'detached')". The reporter diagnosed it: the ESM build imported tweetnacl via a namespace import, but tweetnacl is a CommonJS-only package with no ESM export map, so the real exports sat on nacl.default. A Telnyx collaborator confirmed the fix: the SDK replaced tweetnacl with Node's native crypto.subtle API, which removed the dependency entirely.

Verified resolution: When Telnyx webhook verification throws a detached/undefined error in an ESM project, it is the SDK's tweetnacl import, not your code. Upgrade to a version with the crypto.subtle-based verifier. Note the migration cost the maintainers called out: verify() and unwrap() became async with that change, so await them or your verification will silently not run.

Source URL: https://github.com/team-telnyx/telnyx-node/issues/302