Notifications & Events

EngageIP supports an eventing system that will generate events based on entities in the system. In order and Out of order queuing of events are supported. Subscribers can register for Create, update and delete access to the event queue. EngageIP will provide notification mechanisms that trigger off the underlying event. Two types of notifications will be supported:

  • Email: sending of a predefined email to one or more addresses based on the event trigger
  • Webhooks: A callout to a customer designated URL based on the event trigger

Parameters (tokens) can be associated with notifications to provide additional information about the event. Note that tokens are contextual and dependent on the underlying notification. For example, on a service state transition notification it is possible to provide the corresponding service name as a token. However, on a bill run it is not possible to provide a service name as there are multiple accounts and services that can be associated with a bill run.

Webhooks

EngageIP supports event-based API call outs to other systems via webhooks. An EngageIP webhook is a HTTPS POST that occurs when an event fires. All webhooks are authenticated and conform with the HTTPS protocol. EngageIP will initiate the webhook call over HTTPS to a configurable customer-designated URL. EngageIP will allow the user to specify the path to the receiver service of the callout. The URL must be specified using the HTTP Secure (https://) protocol. EngageIP will not support custom ports for callouts. Up to 2048 characters will be allowed for the Base URL. Customers can subscribe to the notification events listed below and register webhook call outs based on those events.

EventDescription
Service State TransitionTriggered on a service state transition (Preactive->Active, Active->Suspended …)
Account Status ChangeTriggered when the status of an account changes
Account CancellationTriggered when an account has been cancelled
Bill Run StartedTriggered when a bill run is initiated
Bill Run CompletionTriggered when a bill run is completed
Invoice PostedTriggered when an invoice has been posted
Invoice OverdueTriggered when an invoice has breached its payment terms
Invoice DeliveryTriggered when an invoice has been delivered
Invoice Delivery Date + xtTriggered x days after invoice delivery and at a certain time t. x = days and t = time are configurable
RefundTriggered when a refund has been processed on the account
Credit ProcessedTriggered when a credit has been processed on the account
Contract Under CommitTriggered when a contract under commit occurs. This can be done per commit tier.
Dormant SIMTriggered when a SIM is dormant (i.e. has no usage associated with it).
Package CancellationTriggered when a package has been cancelled
Usage Threshold ExceededTriggered when a bucket tier has been used up

Parameters can be added to the call out. Parameters are name value pairs that allow data sources and their values to be added to the callout. Refer to Appendix B for parameters that can be passed in webhooks callouts.

Email Notifications

It is possible to configure SMTP settings for sending of outbound emails. The following SMTP options can be configured per owner.

  • SMTP Server: the email server to user for outgoing email messages, also known as the Outgoing SMTP Server
  • SMTP Port: the port to use for outgoing email messages, default is 25
  • From Name: the name that will appear in the from field
  • From Address: the email address that will appear in the from address field
  • Bcc: blind carbon copies addresses which will not be seen by the To recipient
  • SMTP Username: the username used to log in to your SMTP server
  • SMTP Password: the password used to log in to your SMTP server

Multiple SMTP credentials can be set up per owner. Customers can use this if they need to support multiple email accounts and provide the ability to send certain types of notifications from one account and other types of notifications from a different account. As an example late fee emails might be sent via one account, while service state transition emails might be sent via another.

There will always be a single default set of SMTP Settings. If multiple SMTP settings were configured, the user will be able to specify the default. The default can be changed at any time. EngageIP provides mechanisms for creating canned email notifications. Canned emails can be customized with a descriptive name, subject line, body content and to and from addresses. A canned email can be sent to a configured contact type; this can be a billing contact, service contact, etc.

When setting up canned email notifications, the user is able to configure the SMTP settings used to send the email notification. Email notifications can be sent in HTML and Plain text format. The system provides mechanisms for configuring multiple contact types in the system and specifying which contact type receives the notification. Only one contact of a given contact type can be set up per customer account. If email invoicing is specified, the invoice and invoicing related notifications will be emailed to the billing contact. Non invoicing notifications can be sent to other contacts types - i.e. a service state transition could be sent to a service contact etc. Tokens can be added to emails to provide contextual information within the email message.

For instance, a service state transition email notification can provide information on prior service state and new service state within the message. Email tokens are similar to webhook parameters and the same types of contextual information that are provided with webhooks will be available with emails. Table 2 lists the tokens that are available and Table 3 indicates which tokens will be available for which notifications. Multiple recipients can be selected for sending of email notifications. These recipients can be added to the To, cc and bcc fields.