Subscriptions 2.0

Subscriptions 2.0 represents the latest evolution of Bandwidth’s notification platform, designed to offer greater flexibility and clearer management of event streams. This version introduces a modernized API approach with improved organization of subscription definitions and delivery options.

Key highlights of Subscriptions 2.0 include:

• Subscription Definitions: Predefined event categories simplify understanding and choosing the events you want to track.
• Multiple Delivery Methods: Select between webhook callbacks for automated handling or email notifications for alerts and monitoring.
• Advanced Filtering: Apply filters on subscription criteria to receive only the most relevant event information.
• Account-Specific and System-Wide Support: Easily subscribe to events scoped to your specific accounts or to global system events.
• HMAC: Enhanced security through HMAC signing of webhook payloads

Subscriptions 2.0 is fully supported alongside the existing version, giving you flexibility to adopt new capabilities at your own pace.

Check out the API here!

In the sections ahead, you will learn how to create, manage, and optimize your subscriptions with the new platform to enhance your event-driven integrations.

---

Contents

• Subscription Types
  • Bandwidth App Order Update
    • Order Change Events
    • Note Events

---

Subscription Types

Bandwidth App Order Update

The Bandwidth_App_Order_Update subscription definition can be used to receive webhooks for updates to orders created within the Bandwidth App. These can be filtered by a few properties, including the following: orderType - The type of the order for which the notification is created, such as orders or disconnects eventType - The type of event that happened for the order, either order_change for order status changes or note for a note being added to the order orderId - The order ID generated by the Bandwidth App for a specific order or orders, useful for when you only want notifications about a specific subset of orders These attributes can be specified in the filters field of the request passed to the POST /subscriptions endpoint. If provided, you will only receive order notifications matching the specified filters. This can be omitted if you’d like to receive all notifications for all order types on your account.

The fields for order change and note notifications can differ slightly, but share the same general structure. The following subsections break down what you can expect to receive for each event type.

Order Change Events - Structure

These events represent a change in the status of an order submitted within the Bandwidth App, such as an order moving to a completed status once all work associated with the order has finished.

Field	Type	Description	Example(s)	Required
lastModifiedDate	string (date-time)	The last time the order was modified.	2025-05-05T14:08:26.103Z	Yes
message	string	A human-readable message describing the update.	Created a new number order for 1 number from RALEIGH, NC	Yes
orderId	string (UUID)	Unique identifier for the order generated by Bandwidth.	9cf8daa0-89a4-46aa-a1aa-8b5cf621f218	Yes
orderType	string	The type of the order.	orders, disconnects	Yes
status	string	Current status of the order. The possible statuses will reflect those of the order type the notification is for.	RECEIVED, PROCESSING, COMPLETE, PARTIAL, FAILED	Yes
customerOrderId	string	Customer’s reference ID for the order. This is only sent if one was provided during order creation.	customer-order-id	No
completedPhoneNumbers	Array of strings	List of successful phone numbers in the order in E.164 format. This is only present for orders in a terminal status.	["+19193245298"]	No

Order Change Events - Payload Example

{
  "completedPhoneNumbers": [
    "+19193245298"
  ],
  "lastModifiedDate": "2025-05-05T14:08:26.103Z",
  "message": "Created a new number order for 1 number from RALEIGH, NC",
  "orderId": "9cf8daa0-89a4-46aa-a1aa-8b5cf621f218",
  "orderType": "orders",
  "status": "COMPLETE"
}

Note Events - Structure

These events represent a note being added to an order within the Bandwidth App. This may be a note generated by the system or a note added by a user within your organization or Bandwidth in order to communicate about the status of an order.

Field	Type	Description	Example(s)	Required
lastModifiedDate	string (date-time)	The last time the order was modified.	2025-05-05T14:08:26.103Z	Yes
note	string	The text of the note which was added to the order.	Service activation order was created with ID: 877bf791-fbe0-4448-b9af-bd2b59d7f3d0	Yes
orderId	string (UUID)	Unique identifier for the order generated by Bandwidth.	9cf8daa0-89a4-46aa-a1aa-8b5cf621f218	Yes
orderType	string	The type of the order.	orders disconnects	Yes
customerOrderId	string	Customer’s reference ID for the order. This is only sent if one was provided during order creation	customer-order-id	No

Note Events - Example

{
  "lastModifiedDate": "2025-05-05T14:08:26.103Z",
  "note": "Service activation order was created with ID: 877bf791-fbe0-4448-b9af-bd2b59d7f3d0",
  "orderId": "9cf8daa0-89a4-46aa-a1aa-8b5cf621f218",
  "orderType": "orders"
}