> ## Documentation Index > Fetch the complete documentation index at: https://docs.closient.com/llms.txt > Use this file to discover all available pages before exploring further. # Unified Telnyx webhook (inbound + delivery-receipt) > Single webhook URL for the Telnyx messaging profile (C-4127) — Telnyx posts both inbound messages and delivery receipts to one configured URL, unlike Flowroute/voip.ms which are split across /inbound/ and /status/. Dispatches on data.event_type: `message.received` handles inbound STOP/HELP/START; any other event type (e.g. `message.finalized`) is treated as a delivery-status update. Verifies the Telnyx Ed25519 signature against the raw body BEFORE parsing; invalid/missing signature returns 401. ## OpenAPI ````yaml /openapi/openapi-notifications.json post /notifications/api/v1/sms/webhooks/telnyx/ openapi: 3.1.0 info: title: Notifications API version: 1.0.0 description: > Manage notification preferences and delivery. ## Authentication All endpoints require an API key passed via the `X-API-Key` HTTP header, unless otherwise noted. ``` X-API-Key: csb__ ``` Generate API keys in **Settings > API Keys** in your dashboard, or via the Account API. Session-based (cookie) authentication is also accepted for browser-based access. ## Rate Limits | Tier | Requests / minute | Requests / day | |-------------|-------------------|----------------| | Default | 300 | 10,000 | | Custom | Contact us | Contact us | Rate-limit headers are included on every response so callers can self-throttle without hitting our 429s ("informed governor"): - `RateLimit-Policy` — every active window, e.g. `300;w=60, 10000;w=86400` - `RateLimit-Limit` — quota for the **most-restrictive** currently-active window - `RateLimit-Remaining` — requests left in that window - `RateLimit-Reset` — seconds until that window resets (relative; clock-skew safe) Legacy `X-RateLimit-*` aliases are also emitted for back-compat. `X-RateLimit-Reset` keeps the absolute Unix-timestamp shape to avoid breaking existing consumers. When rate-limited, you receive `429 Too Many Requests` with a `retry_after_seconds` field in the error envelope and a `Retry-After` header. ## Pagination List endpoints return paginated results in this envelope: ```json { "data": [...], "pagination": { "page": 1, "page_size": 25, "total_count": 342, "total_pages": 14, "has_next": true, "has_previous": false } } ``` Use `?page=2&page_size=50` query parameters. Maximum page size is 100. ## Error Responses All errors conform to [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457) with `Content-Type: application/problem+json`: ```json { "type": "https://closient.com/docs/errors/not_found", "title": "Not Found", "status": 404, "detail": "The requested resource was not found.", "error_code": "not_found", "retryable": false, "timestamp": "2026-03-31T12:00:00+00:00" } ``` Common error codes: `unauthorized` (401), `forbidden` (403), `not_found` (404), `validation_error` (422), `rate_limited` (429), `internal_error` (500). termsOfService: https://www.closient.com/terms/ servers: - url: https://www.closient.com security: [] tags: - name: Notifications description: Manage notification preferences and delivery. externalDocs: description: Closient Documentation url: https://docs.closient.com paths: /notifications/api/v1/sms/webhooks/telnyx/: post: tags: - SMS Webhooks summary: Unified Telnyx webhook (inbound + delivery-receipt) description: >- Single webhook URL for the Telnyx messaging profile (C-4127) — Telnyx posts both inbound messages and delivery receipts to one configured URL, unlike Flowroute/voip.ms which are split across /inbound/ and /status/. Dispatches on data.event_type: `message.received` handles inbound STOP/HELP/START; any other event type (e.g. `message.finalized`) is treated as a delivery-status update. Verifies the Telnyx Ed25519 signature against the raw body BEFORE parsing; invalid/missing signature returns 401. operationId: apps_notifications_api_telnyx_webhook parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/TelnyxWebhookSchema' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SMSWebhookAckSchema' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorOut' components: schemas: TelnyxWebhookSchema: description: >- Unified Telnyx webhook envelope (C-4127). A Telnyx messaging profile has exactly ONE configurable webhook URL and posts every event type — inbound messages AND delivery receipts — to it. That's unlike Flowroute/voip.ms, which are split across ``/inbound/`` and ``/status/`` above (that split was built Flowroute-first). This schema/ endpoint is Telnyx-only; Flowroute and voip.ms keep using the split endpoints unchanged. examples: - data: event_type: message.received payload: from: phone_number: '+15035550199' id: 84cca175-9755-4859-b67f-4730d7f58aa3 text: STOP to: - phone_number: '+18445551234' properties: data: $ref: '#/components/schemas/TelnyxEventData' description: Telnyx webhook envelope. required: - data title: TelnyxWebhookSchema type: object SMSWebhookAckSchema: description: Small acknowledgement returned to the carrier after processing. examples: - action: stop ok: true properties: ok: description: Whether the webhook was accepted and processed. title: Ok type: boolean action: default: '' description: >- Action taken for an inbound message (``stop``/``help``/``start``/``none``), empty for status callbacks. title: Action type: string required: - ok title: SMSWebhookAckSchema type: object ErrorOut: description: |- RFC 9457 Problem Details response. All API errors are returned in this format with Content-Type: application/problem+json. examples: - detail: The requested resource was not found. error_code: not_found retryable: false status: 404 timestamp: '2026-03-31T12:00:00+00:00' title: Not Found type: https://closient.com/docs/errors/not_found - detail: Validation error. details: - loc: - body - name msg: Field required type: missing error_code: validation_error retryable: false status: 422 timestamp: '2026-03-31T12:00:00+00:00' title: Validation Error type: https://closient.com/docs/errors/validation_error - detail: Rate limit exceeded. Please try again later. error_code: rate_limited retry_after: 31 retryable: true status: 429 timestamp: '2026-03-31T12:00:00+00:00' title: Rate Limited type: https://closient.com/docs/errors/rate_limited properties: type: description: URI reference identifying the error type. title: Type type: string title: description: Short human-readable summary of the error. title: Title type: string status: description: HTTP status code. title: Status type: integer detail: description: Human-readable explanation of this specific occurrence. title: Detail type: string error_code: description: Machine-readable error code (e.g. not_found, unauthorized). title: Error Code type: string retryable: default: false description: Whether retrying the same request can succeed. title: Retryable type: boolean timestamp: description: ISO 8601 timestamp of when the error occurred. title: Timestamp type: string retry_after: anyOf: - type: integer - type: 'null' description: Seconds to wait before retrying (when applicable). title: Retry After owner_action_required: anyOf: - type: boolean - type: 'null' description: Whether the error requires account owner intervention. title: Owner Action Required details: description: Additional context (validation errors, etc.). title: Details required: - type - title - status - detail - error_code - timestamp title: ErrorOut type: object TelnyxEventData: description: >- The ``data`` envelope of a Telnyx messaging webhook. Reference: https://developers.telnyx.com/docs/messaging/messages/receiving-webhooks examples: - event_type: message.received payload: from: phone_number: '+15035550199' id: 84cca175-9755-4859-b67f-4730d7f58aa3 text: STOP to: - phone_number: '+18445551234' properties: event_type: description: >- Telnyx event type, e.g. ``message.received`` (inbound) or ``message.finalized`` (DLR). title: Event Type type: string payload: $ref: '#/components/schemas/TelnyxMessagePayload' description: The event payload. required: - event_type - payload title: TelnyxEventData type: object TelnyxMessagePayload: description: The ``data.payload`` object of a Telnyx messaging webhook. examples: - from: phone_number: '+15035550199' id: 84cca175-9755-4859-b67f-4730d7f58aa3 text: STOP to: - phone_number: '+18445551234' properties: id: description: Telnyx-assigned message id. title: Id type: string from: $ref: '#/components/schemas/TelnyxPhoneNumber' description: Sender phone number. to: description: Recipient phone number(s). items: $ref: '#/components/schemas/TelnyxRecipient' title: To type: array text: default: '' description: >- Message text, populated on inbound (``message.received``) events only. title: Text type: string required: - id - from - to title: TelnyxMessagePayload type: object TelnyxPhoneNumber: description: A phone-number object as nested in a Telnyx webhook payload. examples: - phone_number: '+15035550199' properties: phone_number: description: E.164 phone number. title: Phone Number type: string required: - phone_number title: TelnyxPhoneNumber type: object TelnyxRecipient: description: A recipient leg of a Telnyx webhook payload's ``to`` array. examples: - phone_number: '+18445551234' status: delivered properties: phone_number: description: E.164 recipient phone number. title: Phone Number type: string status: default: '' description: >- Per-recipient delivery status, populated on delivery-receipt events only (e.g. ``delivered``). title: Status type: string required: - phone_number title: TelnyxRecipient type: object ````