Event subscriptions let you decide which events you want Bandwidth to notify you about and how you wish to receive those notifications, while ensuring you always have the latest information without having to constantly check the system. Here are some examples of what you can do:
Get notifications when orders or events change state
Route updates to a webhook receiver and validate authenticity
Manage notification subscriptions at the account level in one place
Event subscription types
Bandwidth offers two types of event subscriptions: Subscriptions v1 and Subscriptions v2. While we currently support both, we strongly recommend to convert any Subscriptions v1 to Subscriptions v2 at your earliest convenience, as the former will be decommissioned in the future.
Type | Subscriptions v1 | Subscriptions v2 |
Description | The original email and basic auth webhook model. | Enhanced and more flexible notification platform. |
Features |
|
|
Managing event subscriptions
Prerequisites
Before creating or managing event subscriptions, make sure you have:
Access to the Bandwidth App with permissions to view/manage subscriptions for your account.
A destination to receive notifications (webhook URL and auth, or email address).
Subscription labels
To help you determine whether you’re already using Subscriptions v2 or have Subscriptions v1 that are eligible for migration, each option in the Event type drop-down menu will have one of the following labels:
V2: Existing Subscription v2.
Deprecated: Deprecated Subscription v1 with an available Subscription v2. Create a Subscription v2 version of this subscription to begin the migration.
Deprecated (partially migrated): Deprecated Subscription v1 with an already existing Subscription v2 version. Delete this subscription to complete the migration.
Migrating Subscriptions v1
To migrate Subscriptions v1 to Subscriptions v2, please follow this guide.
Managing Subscriptions v2
Add subscription
Note: Subscriptions v2 webhooks require the use of JSON in place of XML. For more information, visit our dev docs.
Log in to the Bandwidth App.
In the side navigation bar, select Account and click Notifications.
Click Add.
Select the Event type for which you'd like to receive notifications
Optional: Provide a Custom name for your subscription.
Select the Delivery Type for your notifications: Email or Webhook.
If you selected Email:
Enter the recipient's email address or select a previously used one from the Email drop-down menu.
Select the Frequency with which you’d like to receive notifications: Instantly (you'll receive an email within a few minutes of a change made to your order) or Daily (you'll receive a daily report of all activity on an order).
If you selected Webhook:
Enter the Callback URL, Username and Password.
Optional: Enter the Shared secret key for HMAC authentication.
Optional: Click Add filter and add up to 5 conditions, which will all be logically combined and applied using the logical AND operator. This allows you to precisely control your notifications, ensuring you receive them only when every single specified condition is met.
Click Add subscription.
Test subscription
Under Subscriptions, find the subscription you want to test.
In the Actions column, click the three dots (⋯) and select Test subscription.
Confirm the destination URL you want to test and click Send.
View subscription history
Under Subscriptions, find the subscription which history you want to view.
In the Actions column, click the three dots (⋯) and select View history.
Delete subscription
Under Subscriptions, find the subscription you want to delete.
In the Actions column, click the three dots (⋯) and select Delete.
Confirm this is the subscription you wish to delete and click Delete Subscription.
