Receiving Webhooks With the Telnyx Verify API V2

You can choose to be notified about verification events by configuring webhooks.

Telnyx supports notifications for the following event types:

Requirements For Enabling Webhooks

For this mechanism to work, you’ll need a publicly accessible HTTP server that can receive our webhook requests at one or more specified URLs. We highly recommend using HTTPS (instead of HTTP). This tutorial walks through setting up a basic application for receiving webhooks.

Hierarchy of URLs

If the whatsapp verification request body is given webhook urls, we will use those. Otherwise, if the verify profile has webhook urls set, we’ll use those. If neither has webhooks, we won’t attempt a webhook delivery. Where primary and failover urls are provided, they are attempted respectively.

Delivery Status Updates

The Telnyx Messaging Services will attempt to notify you about each status update based on the hierarchy of URLs above.

Delivery Status Payload

Here is an example of a webhook request body for a whatsapp message delivered event.

  "data": {
    "event_type": "whatsapp.message.delivered",
    "id": "4ee8c3a6-4995-4309-a3c6-38e3db9ea4be",
    "occurred_at": "2021-01-01T21:32:14.148+00:00",
    "payload": {
      "call_timeout_secs": 299,
      "created_at": "2020-09-14T17:03:32.965812",
      "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
      "phone_number": "+13035551234",
      "record_type": "verification",
      "status": "accepted",
      "timeout_secs": 300,
      "updated_at": "2020-09-14T17:03:32.965812",
      "verification_type": "$OneOfVerificationType",
      "verify_profile_id": "12ade33a-21c0-473b-b055-b3c836e1c292",
      "webhook_failover_url": "",
      "webhook_url": ""
    "record_type": "event"
  "meta": {
    "attempt": 1,
    "delivered_to": ""

Whatsapp Delivery Statuses

Delivery Status Description
whatsapp.message.delivered The message has reached the intended device.
whatsapp.message.seen The message has been opened by the recipient.
whatsapp.message.sending_failed Telnyx has failed to send the message to the upstream provider. Please reach out to our support if you have received this status.
whatsapp.message.delivery_failed The upstream provider has failed to send the message to the receiver. Please reach out to our support if you have received this status.

Telnyx Webhook IPs

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