---
title: "Handle Telnyx Events"
method: POST
path: "/api/v1/telephony/telnyx/events/{workflow_run_id}"
tags: ["main"]
---

# Handle Telnyx Events

`POST /api/v1/telephony/telnyx/events/{workflow_run_id}`

## Request

- Base URL: `https://app.dograh.com`
- URL: `https://app.dograh.com/api/v1/telephony/telnyx/events/{workflow_run_id}`
- Auth: none declared

Handle Telnyx Call Control webhook events.

Telnyx sends all call lifecycle events (call.initiated, call.answered,
call.hangup, streaming.started, streaming.stopped) as JSON POST requests.

Invalid-signature requests are answered with the same 404 "Workflow run
not found" as unknown run ids, deliberately: run ids are sequential
integers, so a distinct 401 on existing runs would let unsigned callers
enumerate which runs exist. The trade-off is that a misconfigured
``webhook_public_key`` presents as a 404 to the caller; the
``logger.warning`` below carries the real reason for operators.

When ``TELEPHONY_WS_TOKEN_SECRET`` is configured, the events webhook URL
minted by the provider carries an HMAC capability token in its query
string (Telnyx preserves query strings on webhook POSTs, unlike media
stream URLs, verified live). The token is verified before any database
lookup, so the reject path does constant work and the run-existence
distinction is closed for both status code and timing. With no secret
configured, the flow falls back to the lookup-then-verify order above.

## Path parameters

- `workflow_run_id` integer, required

## Response `200`

Successful Response

- unknown

## Other responses

- `404`: Not found
- `422`: Validation Error

## Changes

- **2026-11-03** `faa00cf76fcb`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/dograh/apis/dograh-api/changes/api/v1/telephony/telnyx/events/:workflow_run_id/post.md)

---

[API](https://skmtc.dev/dograh/apis/dograh-api.md) - [All operations](https://skmtc.dev/dograh/apis/dograh-api/llms.txt) - [OpenAPI document](https://skmtc.dev/dograh/apis/dograh-api/revisions/faa00cf76fcb?raw)