Skip to main content

Receiving Webhooks for Telnyx Verify

You can choose to be notified about events on your send verifications by configuring webhooks on your verify profile.

Verify delivery status updates ​

The Telnyx Verify Service will attempt to notify you about the following delivery events for the send verification request:

  • verify.sent
  • verify.failed
  • verify.delivered

Delivery status Payload ​

Here is an example of a webhook event where a delivery receipt is returned to the sender after sending a verification:

{
  "data": {
    "event_type": "verify.delivered",
    "id": "010d9dee-d86d-47d0-8d6c-20c0f95a79ec",
    "occurred_at": "2025-10-08T17:16:09.602+00:00",
    "payload": {
      "created_at": "2025-10-08T17:16:08.436941",
      "custom_code": "25565",
      "delivery_status": "delivered",
      "extension": null,
      "failed_attempts": 0,
      "id": "010d9dee-d86d-47d0-8d6c-20c0f95a79ec",
      "mccmnc": null,
      "phone_number": "+13125000000",
      "profile_id": "49000192-1bdb-c56f-3de7-e008ef6da16b",
      "record_type": "verification",
      "status": "pending",
      "timeout_secs": null,
      "type": "sms",
      "updated_at": "2025-10-08T17:16:09.592765"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://webhook.site/af3a92e7-e150-442c-9fe6-61658ce26b1a"
  }
}

Delivery statuses ​

Delivery StatusDescription
sentThe verification has been sent to the upstream provider.
deliveredThe upstream provider has confirmed delivery of the verification.
sending_failedTelnyx has failed to send the verification to the upstream provider. Please reach out to our support if you have received this status.
delivery_failedThe upstream provider has failed to send the verification to the receiver. Please reach out to our support if you have received this status.
delivery_unconfirmedThere is no indication whether or not the verification has reached the receiver. Please reach out to our support if you have received this status

Real-time verification status updates ​

Telnyx Verify now supports webhooks for instant verification status notifications, eliminating the need to poll the API for verification completion.

Benefits ​

  • Eliminates polling - No need to repeatedly check verification status through API calls.
  • Event-driven workflow - React immediately to verification state changes in real-time.
  • Faster user experience - Process verification completions instantly without delays.
  • Improved efficiency - Reduces server load and unnecessary API requests.

Configure webhooks on your Verify profile to receive real-time updates when verifications complete. For specific webhook event types, payload structures, and configuration details, refer to the Telnyx API documentation or contact Telnyx support.

Telnyx Webhook IPs ​

If you use an ACL or Firewall on your network, make sure you whitelist the following subnet(s):

192.76.120.192/27