---
title: "Hosted Number Order Event"
method: POST
path: "hostedNumberOrderEvent"
tags: ["Callbacks"]
---

# Hosted Number Order Event

`POST hostedNumberOrderEvent` (webhook)

Webhook fired when a messaging hosted number order is created, updated, deleted, or progresses through the internal-transfer lifecycle (detected, approval requested, approved, rejected, auto-approved). Inspect `event_type` to distinguish events.

This webhook uses Telnyx headers (telnyx-timestamp, telnyx-signature-ed25519) that are compatible with Standard Webhooks specification for SDK generation. Custom validation logic can map these to standard webhook-timestamp and webhook-signature equivalents. See https://github.com/standard-webhooks/standard-webhooks for details.

## Headers

- `telnyx-timestamp` integer, required — Unix timestamp for replay attack prevention
- `telnyx-signature-ed25519` string, required — Ed25519 signature of timestamp|payload for verification

## Payload

- HostedNumberOrderEvent
  - `data` HostedNumberOrder
    - `record_type` 'event' — Identifies the type of the resource.
    - `id` string, uuid — Unique identifier for the event.
    - `event_type` 'messaging_hosted_numbers_orders.created' | 'messaging_hosted_numbers_orders.updated' | 'messaging_hosted_numbers_orders.deleted' | 'messaging_hosted_numbers_orders.internal_transfer_detected' | 'messaging_hosted_numbers_orders.internal_transfer_approval_requested' | 'messaging_hosted_numbers_orders.internal_transfer_approved' | 'messaging_hosted_numbers_orders.internal_transfer_rejected' | 'messaging_hosted_numbers_orders.internal_transfer_auto_approved' — The type of event being delivered. Internal transfer events are only emitted for orders where the numbers are already active on another Telnyx account.
    - `occurred_at` string, date-time — ISO 8601 formatted date indicating when the event was generated.
    - `payload` HostedNumberOrderEventPayload — Payload delivered with every messaging_hosted_numbers_orders.* event. `approval_deadline` and `decision` are meaningful only for `internal_transfer_*` events.
      - `order_id` string, uuid — The ID of the hosted number order.
      - `order_status` 'pending' | 'provisioning' | 'successful' | 'failed' | 'deleted' | 'carrier_rejected' | 'compliance_review_failed' | 'incomplete_documentation' | 'incorrect_billing_information' | 'ineligible_carrier' | 'loa_file_invalid' | 'loa_file_successful' — Current status of the order.
      - `profile_id` string, uuid — The messaging profile associated with the order.
      - `user_id` string — The organization that owns the order.
      - `numbers` object[]
        - `value` string — Phone number in +E.164 format.
        - `status` 'deleted' | 'failed' | 'failed_activation' | 'failed_carrier_rejected' | 'failed_ineligible_carrier' | 'failed_number_already_hosted' | 'failed_number_not_found' | 'failed_ownership_verification' | 'failed_timeout' | 'ownership_successful' | 'pending' | 'provisioning' | 'successful' — Current status of this phone number within the order.
      - `decision` 'pending' | 'approved' | 'rejected' — Approval decision for the internal transfer. Defaults to `pending` for non-internal-transfer events.
      - `approval_deadline` integer, nullable — Unix timestamp (seconds) by which the losing organization must respond before auto-approval. Populated on internal-transfer events once an approval window has been issued.

## Acknowledgement `200`

The server must return an HTTP 200, otherwise we will reattempt delivery at the failover webhook URL.

---

[API](https://skmtc.net/team-telnyx/apis/telnyx-api.md) · [All operations](https://skmtc.net/team-telnyx/apis/telnyx-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/team-telnyx/telnyx-api/revisions/e32d46c5945b/schema)