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.
Configuring 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:
NoteDon'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.
Types of events
Overall structure of events
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. |
Brand events
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"
}
}
Campaign events
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 |
CAMPAIGN_NUDGE | Nudge event sent by partner CSP to trigger campaign re-review after appeal or rejection. |
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"
}
}
Phone number events
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"
}
}
Campaign Appeals and Nudging Mechanisms
When campaigns are rejected, there are different flows for getting them back into the compliance review queue depending on the campaign type and rejection reason.
Native Campaign Appeals
For native campaigns rejected due to external factors (e.g., website compliance issues), customers can use the campaign appeal endpoint after addressing the issues:
API Endpoint:
curl -X POST 'https://api.telnyx.com/10dlc/campaign/{campaignId}/appeal' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"appealReason": "The website has been updated to include the required privacy policy and terms of service."
}'
Response:
{
"additionalProp1": null,
"additionalProp2": null,
"additionalProp3": null
}
This will update the campaign status from TELNYX_FAILED
to TCR_ACCEPTED
and re-enter the compliance review queue.
Partner Campaign Nudging
For partner campaigns, the appeal process involves the CSP (Campaign Service Provider) sending a CAMPAIGN_NUDGE
event after reviewing and approving customer changes:
CAMPAIGN_NUDGE Webhook Payload Example:
{
"data": {
"event_type": "10dlc.campaign.update",
"id": "example-event-id",
"occurred_at": "2025-07-30T11:07:51.259711+00:00",
"payload": {
"campaignId": "C4D06C2F",
"type": "CAMPAIGN_NUDGE",
"nudgeIntent": "APPEAL_REJECTION",
"description": "The campaign has been reviewed and approved after appeal.",
"cspId": "TNX"
},
"record_type": "event"
},
"meta": {
"attempt": 1,
"delivered_to": "https://your-webhook-url.com"
}
}
Campaign Appeal Scenarios
There are several specific scenarios where campaign appeals may be needed:
1. Native Campaign Rejected for Content Issues
When a customer submits a native campaign and Telnyx rejects it due to issues with the campaign content (e.g., unclear sample messages), the customer can make adjustments to their campaign. Using the campaign update endpoint will automatically reset the campaign's status to TCR_ACCEPTED
so it goes back into the compliance team's review queue.
2. Native Campaign Rejected for External Factors
When a customer submits a native campaign and Telnyx rejects it due to factors outside the campaign object (e.g., website compliance requirements), the customer must:
- Fix the external issues (e.g., update website with required privacy policy)
- Use the appeal API endpoint to get their campaign back in the review queue
Example failure reason:
{
"reason": "Website does not meet compliance requirements."
}
After fixes are made, the appeal request:
curl -X POST 'https://api.telnyx.com/10dlc/campaign/{campaignId}/appeal' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"appealReason": "The website has been updated to include the required privacy policy and terms of service."
}'
3. Partner Campaign Rejected (Any Reason)
For partner campaigns rejected for either content issues or external factors, the process involves the CSP:
- Customer makes required adjustments based on rejection reasons
- CSP reviews the changes and approves them
- CSP forwards a
CAMPAIGN_NUDGE
event to Telnyx - Campaign status changes from
TELNYX_FAILED
toTCR_ACCEPTED
and re-enters compliance review
Important: This nudging mechanism for partner campaigns cannot work with native campaigns.
4. DCA Rejection for External Factors
When Telnyx accepts a campaign but the Direct Connect Aggregator (DCA) rejects it due to external factors:
- Customer makes required external changes (e.g., website updates)
- Customer notifies Telnyx via appropriate appeal mechanism (scenarios 2 or 3)
- Once Telnyx approves the changes, Telnyx generates a nudge webhook that the DCA receives
- Campaign re-enters DCA review queue
5. DCA Rejection for Content Issues
When the DCA rejects a campaign due to campaign content issues:
- Customer updates campaign content (e.g., sample messages)
- Customer notifies Telnyx via appropriate appeal mechanism (scenarios 1 or 3)
- Once Telnyx approves the changes, Telnyx generates a nudge webhook that the DCA receives
- Campaign re-enters DCA review queue
Campaign Status Flow
The typical status flow for campaign appeals is:
- Initial Rejection: Campaign status becomes
TELNYX_FAILED
- Customer Action: Customer addresses the rejection reasons
- Appeal Submission:
- Native campaigns: Use appeal API endpoint or campaign update
- Partner campaigns: CSP sends
CAMPAIGN_NUDGE
- Re-review: Campaign status changes to
TCR_ACCEPTED
and re-enters compliance review
Appeal Metadata
When native campaigns are appealed through the API endpoint, the system stores detailed metadata about the appeal:
Database fields after successful appeal:
campaign_status
: Changes fromTELNYX_FAILED
toTCR_ACCEPTED
appeal_metadata
: JSON object containing appeal details
Example appeal metadata structure:
{
"appealed_at": "2025-07-30T11:07:51.259711+00:00",
"appeal_reason": "The website has been updated to include the required privacy policy and terms of service.",
"previous_status": "TELNYX_FAILED"
}
This metadata allows tracking of the appeal history and provides context for the compliance review team.
NoteThe nudging mechanism for partner campaigns cannot be used with native campaigns. Native campaigns must use the direct appeal API endpoint or campaign update functionality.