# Porting webhooks > \[!IMPORTANT] > > 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](https://help.twilio.com/articles/115002413087-Twilio-Beta-product-support). 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 ```json {"type":"object","refName":"numbers.v1.porting_webhook_configuration_fetch","modelName":"numbers_v1_porting_webhook_configuration_fetch","properties":{"url":{"type":"string","format":"uri","nullable":true,"description":"The URL of the webhook configuration request"},"port_in_target_url":{"type":"string","format":"uri","nullable":true,"description":"The complete webhook url that will be called when a notification event for port in request or port in phone number happens"},"port_out_target_url":{"type":"string","format":"uri","nullable":true,"description":"The complete webhook url that will be called when a notification event for a port out phone number happens."},"notifications_of":{"type":"array","nullable":true,"description":"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.","items":{"type":"string"}},"port_in_target_date_created":{"type":"string","format":"date-time","nullable":true,"description":"Creation date for the port in webhook configuration"},"port_out_target_date_created":{"type":"string","format":"date-time","nullable":true,"description":"Creation date for the port out webhook configuration"}}} ``` ## Webhook types Use the following webhooks associated with port-in request or port-in phone number events. ## Notification events | Resource | Event | Description | | ------------------ | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | PortIn 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. | | PortIn PhoneNumber | `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. | ## Webhook API Configure a webhook to receive the notifications of a port-in request or updates to an existing request. Requests overwrite any existing configurations. > \[!NOTE] > > The Webhook configuration is tied to the account used to create the port-in request or its parent account. ### Example request Configure Webhook ```bash $ curl -X POST 'https://numbers.twilio.com/v1/Porting/Configuration/Webhook' \ --header 'Content-Type: application/json' \ --data '{ "port_in_target_url": "https://www.example.com/port-in", "port_out_target_url": "https://www.example.com/port-out", "notifications_of": [ "PortInWaitingForSignature", "PortInInProgress", "PortInCompleted", "PortInActionRequired", "PortInCanceled", "PortInPhoneNumberWaitingForSignature", "PortInPhoneNumberSubmitted", "PortInPhoneNumberPending", "PortInPhoneNumberCompleted", "PortInPhoneNumberRejected", "PortInPhoneNumberCanceled", "PortOutPhoneNumberCompleted" ] }' \ -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN ``` ```json { "port_in_target_url": "https://www.webhook1.com/", "port_out_target_url": "https://www.webhook2.com/", "notifications_of": [ "PortInWaitingForSignature", "PortInInProgress", "PortInCompleted", "PortInActionRequired", "PortInCanceled", "PortInPhoneNumberWaitingForSignature", "PortInPhoneNumberSubmitted", "PortInPhoneNumberPending", "PortInPhoneNumberCompleted", "PortInPhoneNumberRejected", "PortInPhoneNumberCanceled", "PortOutPhoneNumberCompleted" ], "url": "https://numbers.twilio.com/v1/Porting/Configuration/Webhook" } ``` ## Get webhook configuration `GET https://numbers.twilio.com/v1/Porting/Configuration/Webhook` Retrieve the current webhook configuration. ### Example request {" "} Get Webhook ```js // Download the helper library from https://www.twilio.com/docs/node/install const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio"; // Find your Account SID and Auth Token at twilio.com/console // and set the environment variables. See http://twil.io/secure const accountSid = process.env.TWILIO_ACCOUNT_SID; const authToken = process.env.TWILIO_AUTH_TOKEN; const client = twilio(accountSid, authToken); async function fetchPortingWebhookConfigurationFetch() { const webhook = await client.numbers.v1.webhook.fetch(); console.log(webhook.url); } fetchPortingWebhookConfigurationFetch(); ``` ```python # Download the helper library from https://www.twilio.com/docs/python/install import os from twilio.rest import Client # Find your Account SID and Auth Token at twilio.com/console # and set the environment variables. See http://twil.io/secure account_sid = os.environ["TWILIO_ACCOUNT_SID"] auth_token = os.environ["TWILIO_AUTH_TOKEN"] client = Client(account_sid, auth_token) webhook = client.numbers.v1.webhook.fetch() print(webhook.url) ``` ```csharp // Install the C# / .NET helper library from twilio.com/docs/csharp/install using System; using Twilio; using Twilio.Rest.Numbers.V1; using System.Threading.Tasks; class Program { public static async Task Main(string[] args) { // Find your Account SID and Auth Token at twilio.com/console // and set the environment variables. See http://twil.io/secure string accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID"); string authToken = Environment.GetEnvironmentVariable("TWILIO_AUTH_TOKEN"); TwilioClient.Init(accountSid, authToken); var webhook = await WebhookResource.FetchAsync(); Console.WriteLine(webhook.Url); } } ``` ```java // Install the Java helper library from twilio.com/docs/java/install import com.twilio.Twilio; import com.twilio.rest.numbers.v1.Webhook; public class Example { // Find your Account SID and Auth Token at twilio.com/console // and set the environment variables. See http://twil.io/secure public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID"); public static final String AUTH_TOKEN = System.getenv("TWILIO_AUTH_TOKEN"); public static void main(String[] args) { Twilio.init(ACCOUNT_SID, AUTH_TOKEN); Webhook webhook = Webhook.fetcher().fetch(); System.out.println(webhook.getUrl()); } } ``` ```go // Download the helper library from https://www.twilio.com/docs/go/install package main import ( "fmt" "github.com/twilio/twilio-go" "os" ) func main() { // Find your Account SID and Auth Token at twilio.com/console // and set the environment variables. See http://twil.io/secure // Make sure TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN exists in your environment client := twilio.NewRestClient() resp, err := client.NumbersV1.FetchPortingWebhookConfigurationFetch() if err != nil { fmt.Println(err.Error()) os.Exit(1) } else { if resp.Url != nil { fmt.Println(*resp.Url) } else { fmt.Println(resp.Url) } } } ``` ```php numbers->v1->webhook->fetch(); print $webhook->url; ``` ```ruby # Download the helper library from https://www.twilio.com/docs/ruby/install require 'twilio-ruby' # Find your Account SID and Auth Token at twilio.com/console # and set the environment variables. See http://twil.io/secure account_sid = ENV['TWILIO_ACCOUNT_SID'] auth_token = ENV['TWILIO_AUTH_TOKEN'] @client = Twilio::REST::Client.new(account_sid, auth_token) webhook = @client .numbers .v1 .webhook .fetch puts webhook.url ``` ```bash # Install the twilio-cli from https://twil.io/cli twilio api:numbers:v1:porting:configuration:webhook:list ``` ```bash curl -X GET "https://numbers.twilio.com/v1/Porting/Configuration/Webhook" \ -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN ``` ```json { "port_in_target_url": "https://www.example.com/port-in", "port_out_target_url": "https://www.example.com/port-out", "notifications_of": [ "PortInWaitingForSignature", "PortInInProgress", "PortInCompleted", "PortInActionRequired", "PortInCanceled", "PortInExpired", "PortInPhoneNumberWaitingForSignature", "PortInPhoneNumberSubmitted", "PortInPhoneNumberPending", "PortInPhoneNumberCompleted", "PortInPhoneNumberRejected", "PortOutPhoneNumberCompleted" ], "port_in_target_date_created": "2024-05-14T13:49:04Z", "port_out_target_date_created": "2024-05-14T13:49:07Z", "url": "https://numbers.twilio.com/v1/Porting/Configuration/Webhook" } ``` ## Delete webhook configuration 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}` ### Parameters | Parameter | Description | | ------------- | ---------------- | | webhook\_type | Can be `PORT_IN` | ### Example request ```batch curl -X DELETE 'https://numbers.twilio.com/v1/Porting/Configuration/Webhook/{webhook_type}' \ -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN ``` ### Example response HTTP status code: 204 No content ## Receive the webhook Use the following webhooks associated with port-in request or port-in phone number events. > \[!WARNING] > > When you create a webhook you must use a public URL that can be reached by Twilio. ### 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. ```json { "port_in_request_sid": "port_in_request_sid", "port_in_phone_number_sid": "port_in_phone_number_sid", "last_date_updated": "2024‑01‑25 00:00:00.000", "phone_number": "+1800XXXXXXX", "status": "waiting_for_signature", "portable": "true", "not_portable_reason_code": null, "not_portable_reason": null, "rejection_reason": null, "rejection_reason_code": null } ``` | 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](/docs/glossary/what-e164) 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. | ### Retry policy 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. ### Webhooks security Twilio uses [webhooks](/docs/usage/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](/docs/usage/security#validating-requests).