Porting Webhooks

Porting Webhooks send notifications about events associated with Port In requests, Port In Phone Numbers, and Japan Port Out requests. The parent account will receive all webhooks for any port in requests created on the parent account or any subaccounts.

Webhook Properties

Property nameTypeRequiredDescriptionChild properties

urlstring<uri>

Optional

Not PII

The URL of the webhook configuration request

portInTargetUrlstring<uri>

Optional

Not PII

The complete webhook url that will be called when a notification event for port in request or port in phone number happens

portOutTargetUrlstring<uri>

Optional

Not PII

The complete webhook url that will be called when a notification event for a port out phone number happens.

notificationsOfarray[string]

Optional

Not PII

A list to filter what notification events to receive for this account and its sub accounts. If it is an empty list, then it means that there are no filters for the notifications events to send in each webhook and all events will get sent.

portInTargetDateCreatedstring<date-time>

Optional

Not PII

Creation date for the port in webhook configuration

portOutTargetDateCreatedstring<date-time>

Optional

Not PII

Creation date for the port out webhook configuration

Webhook Types

There are two types of webhooks:

Port In: webhooks associated with a port in request and/or port in phone numbers.
Port Out: webhooks associated with a port out of a Japanese phone number. This is not supported for US phone numbers yet.

Notification Events

Resource	Event	Description
Port In Request	`PortInWaitingForSignature`	A Letter of Authorization (LOA) has been generated for the port in request and is waiting to be signed.
	`PortInInProgress`	The port in request has been submitted to the losing carrier and is progressing normally.
	`PortInCompleted`	All phone numbers in the port in request have been canceled or successfully ported to Twilio.
	`PortInActionRequired`	Something happened with the port in request that requires an action. For example: a phone number has been rejected by the losing carrier.
	`PortInCanceled`	All phone numbers in the port in request have been canceled or the port in request itself.
Port In Phone Number	`PortInPhoneNumberWaitingForSignature`	A Letter of Authorization (LOA) has been generated for the port in request and this number is part of it and is waiting to be signed.
	`PortInPhoneNumberSubmitted`	The phone number has been submitted to the losing carrier for port approval.
	`PortInPhoneNumberPending`	The phone number port has been accepted by the losing carrier.
	`PortInPhoneNumberCompleted`	The phone number in the port in request has been successfully ported to Twilio.
	`PortInPhoneNumberRejected`	The phone number has been rejected by the losing carrier.
	`PortInPhoneNumberCanceled`	The phone number was canceled during the port in process.
Port Out Phone Number	`PortOutPhoneNumberCompleted`	The port out of the phone number has been successful.

Create/Update Webhook API

This API allows the customer to configure a webhook to receive the notifications of a port in or port out request or update an existing one. Requests will overwrite any existing configurations.

(information)

Info

The Webhook configuration is tied to the Account used to create the Port In request or its parent Account.

Example request

Configure Webhook

1$ curl -X POST 'https://numbers.twilio.com/v1/Porting/Configuration/Webhook' \
2--header 'Content-Type: application/json' \
3--data '{
4    "port_in_target_url": "https://www.example.com/port-in",
5    "port_out_target_url": "https://www.example.com/port-out",
6    "notifications_of": [
7       "PortInWaitingForSignature",
8       "PortInInProgress",
9       "PortInCompleted",
10       "PortInActionRequired",
11       "PortInCanceled",
12       "PortInPhoneNumberWaitingForSignature",
13       "PortInPhoneNumberSubmitted",
14       "PortInPhoneNumberPending",
15       "PortInPhoneNumberCompleted",
16       "PortInPhoneNumberRejected",
17       "PortInPhoneNumberCanceled",
18       "PortOutPhoneNumberCompleted"
19    ]
20}' \
21-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Output

1{
2  "port_in_target_url": "https://www.webhook1.com/",
3  "port_out_target_url": "https://www.webhook2.com/",
4  "notifications_of": [
5    "PortInWaitingForSignature",
6    "PortInInProgress",
7    "PortInCompleted",
8    "PortInActionRequired",
9    "PortInCanceled",
10    "PortInPhoneNumberWaitingForSignature",
11    "PortInPhoneNumberSubmitted",
12    "PortInPhoneNumberPending",
13    "PortInPhoneNumberCompleted",
14    "PortInPhoneNumberRejected",
15    "PortInPhoneNumberCanceled",
16    "PortOutPhoneNumberCompleted"
17  ],
18  "url": "https://numbers.twilio.com/v1/Porting/Configuration/Webhook"
19}

Get Webhook API

GET https://numbers.twilio.com/v1/Porting/Configuration/Webhook

This API allows the customer to retrieve the current webhook configuration.

Example request

Get Webhook

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchPortingWebhookConfigurationFetch() {
11  const webhook = await client.numbers.v1.webhook.fetch();
12
13  console.log(webhook.url);
14}
15
16fetchPortingWebhookConfigurationFetch();

Response

Note: This shows the raw API response from Twilio. Responses from SDKs (Java, Python, etc.) may look a little different.

1{
2  "port_in_target_url": "https://www.example.com/port-in",
3  "port_out_target_url": "https://www.example.com/port-out",
4  "notifications_of": [
5    "PortInWaitingForSignature",
6    "PortInInProgress",
7    "PortInCompleted",
8    "PortInActionRequired",
9    "PortInCanceled",
10    "PortInExpired",
11    "PortInPhoneNumberWaitingForSignature",
12    "PortInPhoneNumberSubmitted",
13    "PortInPhoneNumberPending",
14    "PortInPhoneNumberCompleted",
15    "PortInPhoneNumberRejected",
16    "PortOutPhoneNumberCompleted"
17  ],
18  "port_in_target_date_created": "2024-05-14T13:49:04Z",
19  "port_out_target_date_created": "2024-05-14T13:49:07Z",
20  "url": "https://numbers.twilio.com/v1/Porting/Configuration/Webhook"
21}

Delete Webhook API

This API allows the customer to delete a specific webhook configuration. It could take up to a few minutes for this action to take effect since the configuration may be cached.

HTTP Method: DELETE Path: https://numbers.twilio.com/v1/Porting/Configuration/Webhook/{webhook_type}

Parameters

Parameter	Description
Webhook_type	It can be `PORT_IN` or `PORT_OUT`

Example Request

1curl -X DELETE 'https://numbers.twilio.com/v1/Porting/Configuration/Webhook/{webhook_type}' \
2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Example Response:

HTTP status code: 204 No content

Receiving the webhook

There are two types of webhooks that can be configured for porting:

Port In: webhooks associated with a port in request and/or port in phone numbers.
Port Out: webhooks associated with a port out of a Japanese phone number. Not currently supported in US porting.

(warning)
Warning
When you are creating a Webhook is very important to have a public URL that can be reached by Twilio, otherwise, the webhook will not work.

Port In Webhook

The port in webhook sends the following request body in a POST HTTP request and expects to receive an HTTP 200 OK response.

1{
2  "port_in_request_sid": "port_in_request_sid",
3  "port_in_phone_number_sid": "port_in_phone_number_sid",
4  "last_date_updated": "2024‑01‑25 00:00:00.000",
5  "phone_number": "+1800XXXXXXX",
6  "status": "waiting_for_signature",
7  "portable": "true",
8  "not_portable_reason_code": null,
9  "not_portable_reason": null,
10  "rejection_reason": null,
11  "rejection_reason_code": null
12}

Field	Description
`port_in_request_sid`	The `SID` of the port in request
`port_in_phone_number_sid`	The `SID` of the port in phone number if the event is for a phone number otherwise it should be null.
`last_date_updated`	The date for the last time that the status of the port in request or port in phone number was updated.
`phone_number`	The phone number in e164 format if this is an event for a phone number. Otherwise, this is null.
`status`	The current status of the port in request or port in phone number.
`portable`	If the event is for a phone number, this field is a Boolean describing whether the number is portable or not.
`not_portable_reason_code`	If the number is not portable, it shows the not portable reason code.
`not_portable_reason`	If the number is not portable, it shows the not portable reason.
`rejection_reason`	If the number was rejected by the vendor, it shows the rejection reason.
`rejection_reason_code`	If the number was rejected by the vendor, it shows the rejection reason code.

Port Out Webhook

The Port Out webhook sends the following body in a POST HTTP request and it continues sending the request until it receives a 200 OK response.

1{
2  "port_out_phone_number_sid": "port_out_phone_number_sid",
3  "last_date_updated": "2024‑01‑25 00:00:00.000",
4  "phone_number": "+1800XXXXXXX",
5  "status": "completed"
6}

Field	Description
`port_out_phone_number_sid`	The `SID` of the port out phone number
`last_date_updated`	The date for the last time that the status of the port out phone number was updated
`phone_number`	The phone number in e164 format
`status`	The current status of the port out phone number

Retry Policy

The Port In and Port Out webhook requests do up to 10 retries. The backoff interval doubles after each retry. Retries start 5 minutes after the first attempt and end after 21 hours.

Webhooks Security

Twilio uses webhooks to notify your application about events occurring in your Twilio products, sending these updates to the URL you configured. To safeguard the communication between Twilio and your web application, Twilio supports encryption and cryptographically signs its requests. These signatures ensure the authenticity of requests from Twilio. You can verify a request's legitimacy by following the guidelines in the Twilio Security documentation.

Porting Webhooks

Webhook Properties

Webhook Types

Notification Events

Create/Update Webhook API

Info

Example request

Output

Get Webhook API

Example request

Response

Delete Webhook API

Parameters

Example Request

Example Response:

Receiving the webhook

Warning

Port In Webhook

Port Out Webhook

Retry Policy

Webhooks Security