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

• HMAC Signature Implementation
• Subscription Types
  • Bandwidth App Order Update
    • Order Change Events
    • Note Events

---

HMAC Signature Implementation

To ensure the security of webhook payloads, Bandwidth uses HMAC signing. This allows receivers to verify the authenticity of the payloads received from Bandwidth.

How It Works

Bandwidth generates an HMAC signature using a secret key and the payload body. The base64-encoded signature is included in the X-Bandwidth-Signature-SHA-256 header of the webhook request. Consumers can use this signature to verify the integrity and authenticity of the payload.

warning

The signature is highly sensitive to the exact formatting of the payload, including whitespace and character encoding. Any changes to the payload body, even minor ones, will result in a different signature and cause verification to fail. Always use the raw request body for signature validation.

Steps to Verify the HMAC Signature

1. Retrieve the Signature: Extract the X-Bandwidth-Signature-SHA-256 header from the webhook request.
2. Generate the Signature Locally:

• Use the same secret key as provided to Bandwidth.
• Hash the received body using the HMAC algorithm (SHA256).

3. Compare Signatures: Compare the locally generated signature with the one provided in the X-Bandwidth-Signature-SHA-256 header. If they match, the payload is authentic.

Example POST Request

POST https://your-domain.com/webhooks/your-endpoint
Authorization: Basic aGVsbG86d29ybGQ=
Content-Type: application/json
X-Bandwidth-Signature-SHA-256: AbCdEfGhIjKlMnOpQrStUvWxYz1234567890==

{
  "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"
}

Example Verification Code (Python)

import base64
import hashlib
import hmac

def hmac_256(key, data):
    """Generate HMAC SHA256 hash."""

    return hmac.new(key.encode(), data.encode(), hashlib.sha256).digest()

def validate_signature(received_signature, request_body, secret):
    """Verify the HMAC signature with the given secret."""

    generated_signature = base64.b64encode(hmac_256(secret, request_body)).decode()

    return hmac.compare_digest(received_signature, generated_signature)

# Usage
secret = 'your_shared_secret'
received_signature = 'received_signature'
request_body = 'body_of_the_request'
is_valid = validate_signature(received_signature, request_body, secret)

if is_valid:
    print('The webhook is valid.')
else:
    print('Invalid webhook delivery.')

---

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"
}