Skip to contentSkip to navigationSkip to topbar
On this page

Porting webhooks


(new)

Public Beta

The Porting API and webhooks are in Public Beta. The information in this document could change. We might add or update features before the product becomes Generally Available. Beta products don't have a Service Level Agreement (SLA). Learn more about beta product support(link takes you to an external page).

Porting webhooks send notifications about events associated with port-in requests and port-in phone numbers. The parent account receives all webhooks for any port-in requests created on the parent account or any subaccounts.


Webhook Properties

webhook-properties page anchor
Property nameTypeRequiredDescriptionChild properties
urlstring<uri>

Optional

Not PII

The URL of the webhook configuration request


portInTargetUrlstring<uri>

Optional

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

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


notificationsOfarray[string]

Optional

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

Creation date for the port in webhook configuration


portOutTargetDateCreatedstring<date-time>

Optional

Creation date for the port out webhook configuration


Use the following webhooks associated with port-in request or port-in phone number events.


ResourceEventDescription
PortIn requestPortInWaitingForSignatureA Letter of Authorization (LOA) has been generated for the port-in request and is waiting to be signed.
PortInInProgressThe port-in request has been submitted to the losing carrier and is progressing normally.
PortInCompletedAll phone numbers in the port-in request have been canceled or successfully ported to Twilio.
PortInActionRequiredSomething happened with the port-in request that requires an action. For example: a phone number has been rejected by the losing carrier.
PortInCanceledAll phone numbers in the port-in request have been canceled or the port-in request itself.
PortIn PhoneNumberPortInPhoneNumberWaitingForSignatureA 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.
PortInPhoneNumberSubmittedThe phone number has been submitted to the losing carrier for port approval.
PortInPhoneNumberPendingThe phone number port has been accepted by the losing carrier.
PortInPhoneNumberCompletedThe phone number in the port-in request has been successfully ported to Twilio.
PortInPhoneNumberRejectedThe phone number has been rejected by the losing carrier.
PortInPhoneNumberCanceledThe phone number was canceled during the port-in process.

Configure a webhook to receive the notifications of a port-in request or updates to an existing request. Requests 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

example-request page anchor
Configure WebhookLink to code sample: 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 configuration

get-webhook-configuration page anchor

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

Retrieve the current webhook configuration.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const 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
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function fetchPortingWebhookConfigurationFetch() {
11
const portingWebhookConfigurationFetch =
12
await client.numbers.v1.portingWebhookConfigurationFetch.fetch();
13
14
console.log(portingWebhookConfigurationFetch.url);
15
}
16
17
fetchPortingWebhookConfigurationFetch();

Response

Note about this response
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 configuration

delete-webhook-configuration page anchor

Delete a specific webhook configuration. It could take 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}

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

HTTP status code: 204 No content


Use the following webhooks associated with port-in request or port-in phone number events.

(warning)

Warning

When you create a webhook you must use a public URL that can be reached by Twilio.

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
}
FieldDescription
port_in_request_sidThe SID of the port-in request
port_in_phone_number_sidThe SID of the port-in phone number if the event is for a phone number otherwise it should be null.
last_date_updatedThe date for the last time that the status of the port-in request or port-in phone number was updated.
phone_numberThe phone number in e164 format if this is an event for a phone number. Otherwise, this is null.
statusThe current status of the port-in request or port-in phone number.
portableIf the event is for a phone number, this field is a Boolean describing whether the number is portable or not.
not_portable_reason_codeIf the number is not portable, it shows the not portable reason code.
not_portable_reasonIf the number is not portable, it shows the not portable reason.
rejection_reasonIf the number was rejected by the vendor, it shows the rejection reason.
rejection_reason_codeIf the number was rejected by the vendor, it shows the rejection reason code.

Twilio retries each webhook request up to 10 times. The backoff interval doubles after each retry. Retries begin 5 minutes after the first attempt and stop after 21 hours.

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.