Skip to main content

Order Webhook

The notification webhook API is used to notify customers of events and changes that occur with various feature and service orders that are being processed by the Bandwidth Numbers API on their behalf. In general this notification webhook will be called whenever an order that is in-scope changes state or has a note added to it. Alternatively, notification webhook will be called whenever a subscribed event occurs

When an order changes OR when numbers in customer account are impacted due to orders placed outside of their account the Bandwidth Dashboard API will POST a pre-defined payload to our customer at the URL that they have defined by use of the /accounts/{{accountId}}/subscriptions API call. Please see the subscription documentation to understand how to register the notification webhook API with the Bandwidth Numbers API.

Order Types#

Order typeNotified states
portinsPENDING_DOCUMENTS, SUBMITTED, FOC, REQUESTED_SUPP, COMPLETE, CANCELLED, EXCEPTION, REQUESTED_CANCEL
ordersCOMPLETE, PARTIAL, BACKORDERED, FAILED
portoutsCOMPLETE
disconnectsCOMPLETE, PARTIAL, FAILED
dldasRECEIVED, PROCESSING, COMPLETE, PARTIAL, FAILED
lsrordersPENDING, FOC, EXCEPTION, COMPLETE, CANCELLED, PARTIAL, FAILED
e911sRECEIVED, PROCESSING, COMPLETE, ADJUSTED_COMPLETE, PARTIAL, ADJUSTED_PARTIAL, FAILED
tnoptionsRECEIVED, PROCESSING, COMPLETE, PARTIAL, FAILED
externalTnsCOMPLETE, PARTIAL, FAILED
lidbPROCESSING, COMPLETE, PARTIAL, FAILED
bulkPortinsDRAFT, IN_PROGRESS, NEEDS_ATTENTION, PARTIAL, COMPLETED, CANCELLED
importtnordersCOMPLETE, PARTIAL, FAILED, EXCEPTION
removeImportedTnOrdersPROCESSING, COMPLETE, PARTIAL, FAILED
emergencyNotificationGroupCOMPLETE, FAILED
emergencyEndpointGroupCOMPLETE, FAILED

Parameters#

ParameterTypeDescription
SubscriptionIdStringSubscription ID that the notification is in response to.
OrderTypeStringType of order that the notification applies to.
OrderIdStringOrder ID of the order that has changed
CustomerOrderIdStringCustomer order ID of the order that has changed (the element is considered optional, and will only be provided if the related order has a Customer Order Id)
StatusStringNew state of the order
MessageStringMessage if one was attached as part of the state change. This will often be present in error cases.
NoteStringBody of any note that was attached to the order, if applicable.
CompletedTelephoneNumbersList of <TelephoneNumber>List of the completed telephone numbers for Port-in/Port-out/New Number/Disconnect orders in terminal state

Example of an Order Notification#

POST your_url.com/webhookService HTTP/1.1
Content-Type: application/xml; charset=utf-8
<?xml version="1.0"?>
<Notification>
<SubscriptionId>...</SubscriptionId>
<OrderType>OrderId</OrderType>
<CustomerOrderId>...</CustomerOrderId>
<Status>COMPLETE</Status>
<CompletedTelephoneNumbers>
<TelephoneNumber> ... </TelephoneNumber>
</CompletedTelephoneNumbers>
</Notification>