10DLC A2P Provisioning Webhooks

• Campaign Webhooks
  • Campaign Add Webhook
    • Campaign Add Payload
    • Campaign Add Status Codes
    • Campaign Add Properties
  • Campaign Delete Webhook
    • Campaign Delete Payload
    • Campaign Delete Status Codes
    • Campaign Delete Properties
  • Campaign Number Pool Webhook
    • Campaign Number Pool Payload
    • Campaign Number Pool Status Codes
    • Campaign Number Pool Properties
• Provisioning Webhooks
  • Provision Add Webhook
    • Provision Add Payload
    • Provision Add Status Codes
    • Provision Add Properties
  • Provision Delete Webhook
    • Provision Delete Payload
    • Provision Delete Status Codes
    • Provision Delete Properties
• Webhook Configuration
  • Webhook Server IP Addresses
  • Webhook Endpoint Failures

Webhooks push real-time server-to-server notifications of campaign registration and line provisioning state changes occurring in your account. You must provide a public facing url to receive webhook callbacks. Webhooks payloads are in application/json format.

Campaign Webhooks

You can subscribe to the following Campaign Events.

Campaign Add Webhook

Campaign Add Payload

The campaign/add payload contains properties specific to the activation of a campaign.

POST /campaign/add HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 180
Host: your-domain.com
User-Agent: Apache-HttpClient/4.5.7 (Java/1.8.0_201)

{
  "statusCode": 0,
  "description": "Campaign Active",
  "campaignId": "abc123",
  "brandId": "xyz456",
  "mnoId": [10017, 10035, 10037],
  "numberPoolSubId": "xyz456",
  "eventDate": "2020-11-13T17:01:17.123Z"
}

Campaign Add Status Codes

The campaign/add status code will be one of the following values:

Campaign Add Properties

Campaign Delete Webhook

Campaign Delete Payload

The campaign/delete payload contains properties specific to the deactivation of a campaign.

POST /campaign/delete HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 180
Host: your-domain.com
User-Agent: Apache-HttpClient/4.5.7 (Java/1.8.0_201)

{
  "statusCode": 0,
  "description": "Campaign Expired",
  "campaignId": "abc123",
  "brandId": "xyz456",
  "mnoId": [10017, 10035, 10037],
  "numberPoolSubId": "xyz456",
  "eventDate": "2020-11-13T17:01:17.123Z"
}

Campaign Delete Status Codes

The campaign/delete status code will be one of the following values:

Campaign Delete Properties

Campaign Number Pool Webhook

Campaign Number Pool Payload

The campaign/numberPool payload contains properties specific to a campaign when a number pool has been added, changed, or removed.

POST /campaign/numberPool HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 195
Host: your-domain.com
User-Agent: Apache-HttpClient/4.5.7 (Java/1.8.0_201)

{
  "statusCode": 0,
  "description": "Number pool added to campaign",
  "campaignId": "abc123",
  "brandId": "xyz456",
  "mnoId": [10017, 10035, 10037],
  "numberPoolSubId": "xyz456",
  "eventDate": "2020-11-13T17:01:17.123Z"
}

Campaign Number Pool Status Codes

The campaign/numberPool status code will be the following value:

Campaign Number Pool Properties

Using Sub-ID’s for Number Pools

The numberPoolSubId is a unique identifier for the number pool. It is used to identify the specific number pool associated with the campaign.

• When a number pool is assigned to a campaign, a campaign/numberPool webhook will be sent.
• Subsequently, each phone number associated with that pool will have its numberPoolSubId included in the provision/add webhook.
• The numberPoolSubId should be be set in OSR (Override Services Registry) on the sub_id property for each phone number.

Provisioning Webhooks

You can subscribe to the following Provisioning Events.

Provisioning Flow and Webhook Timing

When sending a provisioning request (POST /v3/lines), you will immediately receive a 202 Accepted HTTP status code. However, it should be clarified that this does not confirm the final status of the request, in order to follow up the result you must listen to the webhook notification:

• The provision/add webhook will be sent once the provisioning operation is fully completed (either successfully or with failure).
• See Provision Add Webhook for the full payload and possible statuses.

Typical Timeline Example:

1. Client sends POST to provision a phone number.
2. Server responds with 202 Accepted immediately.
3. After the provisioning process has been completed, a webhook provision/add will arrive at the configured webhook URL.
4. The webhook contains the final statusCode indicating success (200) or error.

Provision Add Webhook

Provision Add Payload

The provision/add payload contains properties specific to the status of a line provisioning (add) request.

POST /provision/add HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 192
Host: your-domain.com
User-Agent: Apache-HttpClient/4.5.7 (Java/1.8.0_201)

{
  "statusCode": 200,
  "description": "Line Provisioned",
  "lineNumber": "+12065551234",
  "campaignId": "abc123",
  "numberPoolSubId": "xyz456",
  "vendorCustomerId": "werwiou789",
  "requestId": "def789",
  "eventDate": "2020-11-13T17:01:17.123Z"
}

Provision Add Status Codes

The provision/add status code will be one of the following values:

Provision Add Properties

Provision Delete Webhook

Provision Delete Payload

The provision/delete payload contains properties specific to the progress of a line de-provisioning (delete) request.

POST /provision/delete HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 188
Host: your-domain.com
User-Agent: Apache-HttpClient/4.5.7 (Java/1.8.0_201)

{
  "statusCode": 200,
  "description": "Line Deleted",
  "lineNumber": "+12065551234",
  "campaignId": "abc123",
  "numberPoolSubId": "xyz456",
  "vendorCustomerId": "werwiou789",
  "requestId": "def789",
  "eventDate": "2020-11-13T17:01:17.123Z"
}

Provision Delete Status Codes

The provision/delete webhook will return the following status code:

Provision Delete Properties

Webhook Configuration

More details to come with the final documentation for webhooks.