2025-01-01

Phone number status updated

Triggered when a phone number's service or health status changes. Use this to monitor phone number health and availability.

Service status (previous_status / new_status):

  • ACTIVE — Phone number is in service and can send/receive messages
  • FLAGGED — Phone number has been flagged by the carrier and may have limited functionality

Reputation (previous_reputation / new_reputation):

  • HEALTHY — The line is in good standing. Send normally.
  • AT_RISK — Warning signs on the line: engagement is low across many of its conversations, or it's starting too many brand-new conversations in a single day — and a spike in send volume can add to either. Slow the line's send pace, avoid opening many new conversations at once, and review your messaging patterns.
  • CRITICAL — Strong signals that messages from this line aren't landing well. Pause outbound on the line until it recovers.
postWebhookphone_number.status_updated.v2025-01-01

Payload

api_versionstring required

API version for the webhook payload format

webhook_versionstring required

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

event_type'message.sent' | 'message.received' | 'message.read' | 'message.delivered' | 'message.failed' | 'message.edited' | 'reaction.added' | 'reaction.removed' | 'poll.received' | 'poll.failed' | 'poll.sent' | 'poll.delivered' | 'poll.read' | 'poll.updated' | 'poll.vote.added' | 'poll.vote.removed' | 'poll.reaction.added' | 'participant.added' | 'participant.removed' | 'chat.created' | 'chat.group_name_updated' | 'chat.group_icon_updated' | 'chat.group_name_update_failed' | 'chat.group_icon_update_failed' | 'chat.background_updated' | 'chat.background_update_failed' | 'chat.typing_indicator.started' | 'chat.typing_indicator.stopped' | 'phone_number.status_updated' | 'phone_number.assigned' | 'phone_number.released' | 'contact_card.received' | 'call.initiated' | 'call.ringing' | 'call.answered' | 'call.ended' | 'call.failed' | 'call.declined' | 'call.no_answer' | 'location.sharing.started' | 'location.sharing.stopped' | 'payment.succeeded' | 'payment.canceled' | 'payment.expired' | 'payment.declined' | 'payment.authorized' | 'connection.created' | 'connection.revoked' | 'zero_day_retention.updated' | 'phone_number.forwarding_updated' | 'environment.line_moved' | 'contact_card.created' | 'contact_card.updated' | 'contact_card.deleted' | 'api_token.created' | 'api_token.renamed' | 'api_token.expiry_scheduled' | 'api_token.expired' | 'api_token.activated' | 'api_token.deleted' | 'environment.created' | 'environment.renamed' | 'environment.deleted' | 'webhook_subscription.created' | 'webhook_subscription.deleted' | 'webhook_subscription.target_url_changed' | 'webhook_subscription.enabled' | 'webhook_subscription.disabled' | 'webhook_subscription.events.updated' | 'webhook_subscription.phone_numbers.updated' | 'webhook_subscription.routing_headers_set' | 'webhook_subscription.routing_headers_cleared' | 'team_member.added' | 'team_member.signed_in' | 'team_member.signed_out' required

The type of event

event_idstring uuid required

Unique identifier for this event (for deduplication)

created_atstring date-time required

When the event was created

trace_idstring required

Trace ID for debugging and correlation across systems.

partner_idstring required

Partner identifier. Present on all webhooks for cross-referencing.

Example payload

{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "phone_number.status_updated",
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2025-11-23T17:30:00Z",
  "trace_id": "abc123def456",
  "partner_id": "partner_abc123",
  "data": {
    "phone_number": "+15551234567",
    "previous_status": "ACTIVE",
    "new_status": "FLAGGED",
    "previous_reputation": "HEALTHY",
    "new_reputation": "HEALTHY",
    "changed_at": "2024-01-15T10:30:00Z"
  }
}

Response

Webhook received successfully

Changes

Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.