10DLC Event Notifications

You can choose to be notified about events on your 10DLC Brands, Campaigns and Phone Numbers by configuring webhooks.

For this mechanism to work, you’ll need a publicly accessible HTTP server that can receive our webhook requests at one or more specified URLs. We highly recommend using HTTPS (instead of HTTP). This tutorial walks through setting up a basic application for receiving webhooks.

To receive notifications for brands you need to either provide the webhooks at the creation of the brand or you may update an existing brand. On both cases you have to pass your webhooks in the webhookURL and webhookFailoverURL.

webhookFailoverURL is optional. Here is an example of updating the webhooks of a brand:

Note

Don't forget to update YOUR_API_KEY here.

curl -X PUT https://api.telnyx.com/10dlc/brand/:brandid \
  -H 'Content-type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{"webhookURL":"https://mywebhooks.com/c5e5e598-95b3-4076-bfe2-c7d2c58ec57f", "webhookFailoverURL":"http://mywebhooks.com/ae20ec14-1c23-4275-add5-3290706b450f"}'

The same applies for campaign event notifications. Webhooks can be provided either upon campaign creation or through an update.

Webhooks configured for a campaign are also leverage for event notification with phone numbers associated to said campaign. Phone number notifications are triggered also for shared campaigns.

Here is an example of a webhook event:

{
  "data": {
    "event_type": "10dlc.brand.update",
    "id": "02d4f0e2-7a9d-4ebf-86b9-3df81e862d49",
    "occurred_at": "2024-08-07T17:22:37.328+00:00",
    "payload": {
      "brandId": "97091164-e814-435c-9c1b-14ab2d18e987",
      "brandName": "Some Brand LLC",
      "description": "Brand BBRAND1 is added",
      "eventType": "BRAND_ADD",
      "status": "success",
      "tcrBrandId": "BBRAND1",
      "type": "TCR_BRAND_WEBHOOK"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://mywebhooks.com/310fda1a-d415-4827-837b-5f7e72657b65"
  }
}

Let's have a closer look at the data key:

Field	Description
event_type	We currently support 3 types of events: 10dlc.brand.update, 10dlc.campaign.update and 10dlc.phone_number.update for updates related to brands, campaigns and phone numbers respectively.
id	Unique id of this event.
occurred_at	Timestamp of the event.
payload	The content of the payload varies according with the type of event. Below we listed the different payload types grouped by entity.

Payload type	Description
REGISTRATION	Failures during the registration process. The payload will contain a field called reasons with more details about the errors encountered.
REVET	Success of the revetting request operation. See this for more details .
ORDER_EXTERNAL_VETTING	Notification on the process of ordering an external vetting. The status field indicates if the order succeed or failed.
TCR_BRAND_WEBHOOK	Notifications received from TCR. The table below has a list of all TCR events that are included here.

Here is a list of all TCR events under the TCR_BRAND_WEBHOOK type:

TCR Event	Description
BRAND_ADD	Brand successfully added on TCR.
BRAND_APPEAL_ADD	A Brand appeal was added.
BRAND_APPEAL_COMPLETE	The result of a brand appeal.
BRAND_REVET	Result of a brand revet request.

Here is an example of a REGISTRATION notification:

{
  "data": {
    "event_type": "10dlc.campaign.update",
    "id": "456abc67-7a9d-4ebf-86b9-3df81e862d49",
    "occurred_at": "2024-08-07T17:22:37.328+00:00",
    "payload": {
      "brandId": "b0e2ec67-b26f-4c77-affc-d10f4d1780d3",
      "status": "failed",
      "type": "REGISTRATION",
      "reasons": [
        {
          "fields": [
            "ein"
          ],
          "description": "Invalid EIN - EIN is a nine-digit number. The format is XX-XXXXXXX. The \"-\" symbol is also accepted."
        }
      ]
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://mywebhooks.com/310fda1a-d415-4827-837b-5f7e72657b65"
  }
}

Payload type	Description
REGISTRATION	Notifications about failures during the registration process. The errors will be listed in the reasons field of the payload.
NUMBER_POOL_PROVISIONED	Success on provisioning a number pool.
NUMBER_POOL_DEPROVISIONED	Success on deprovisioning a number pool.
TCR_EVENT	Notification received from TCR.
MNO_REVIEW	MNO review results. The payload contains a status field that indicates if the campaign was ACCEPTED or REJECTED. In case of rejection, the description field provides a reason.
VERIFIED	Campaign registration was verified.

Here is a list of all TCR events under the TCR_EVENT type:

TCR Event	Description
CAMPAIGN_ADD	Campaign successfully added.
CAMPAIGN_EXPIRED	Campaign is expired.
CAMPAIGN_RESUBMISSION	Campaign resubmission

Here is an example of a VERIFIED notification:

{
  "data": {
    "event_type": "10dlc.campaign.update",
    "id": "456abc67-7a9d-4ebf-86b9-3df81e862d49",
    "occurred_at": "2024-08-07T17:22:37.328+00:00",
    "payload": {
      "brandId": "BBRAND1",
      "campaignId": "CCAMP1",
      "createdDate": "2024-07-06T14:22:37.328+00:00",
      "cspId": "CSPID1",
      "type": "VERIFIED",
      "isTMobileRegistered": true
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://mywebhooks.com/310fda1a-d415-4827-837b-5f7e72657b65"
  }
}

Payload type	Description
ASSIGNMENT	Notifications about the phone number assignment process. In case of failure, an error message is displayed in the reasons field. That field is empty in case of a successful assignment.
DELETION	Notifications about the phone number removal process. In case of failure, an error message is displayed in the reasons field. That field is empty in case of a successful removal.
STATUS_UPDATE	The status of the phone number was updated. The new status is shown in the status field.

Here is an example of a successful ASSIGNMENT notification:

{
  "data": {
    "event_type": "10dlc.phone_number.update",
    "id": "123abc67-7a9d-4ebf-86b9-3df81e862d49",
    "occurred_at": "2024-08-07T17:22:37.328+00:00",
    "payload": {
      "campaignId": "751c6a5c-907b-43a9-8ada-ba1dc8335b07",
      "phoneNumber": "+16715455939",
      "status": "success",
      "type": "ASSIGNMENT",
      "reasons": []
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://mywebhooks.com/310fda1a-d415-4827-837b-5f7e72657b65"
  }
}