How One Of Nigeria's Big E-Commerce Players Developed An In-House Notifications-As-A-Service System

Notifications are at the heart of every client facing product for any e-commerce company. This is especially true for us at Konga as notifications are also important to most internal products that we build.

Notifications afford us an easy way to keep in touch with our customers, keep them in the know of what is happening to their orders and for the merchants, let them know what is happening in their store. We seldom send out push notifications for our mobile apps — Android and iOS — but, SMS and e-mails form the core of our notifications.

As the Konga engineering team grew and different teams had the need to add notifications for their different products, we had the problem that most engineering teams face; "everyone implementing things differently".

Enter Hermes

Hermes is Konga's in-house notification service – Notifications-as-a-Service (NaaS). It provides a simple RESTFul API for sending notifications; emails and SMS.

The major benefit of Hermes is that it abstracts the underlying API of SMS and transactional email providers into one simple and consistent RESTFul endpoint — /v1/endpoint — that does one thing and one thing well; send notifications.

Hermes accepts sample payload in this format.

{
    "medium": "email",
    "name": “app_template_name",
    "recipient": [email protected]",
    "subject": “Your order has been shipped",
    "sender": "[email protected]",
    "sender_id": “Owner",
    "params": {
        “customer_name": “James Bond”,
        “order_number”: “R123456789"
    }
}

The above payload is simple and almost self-explanatory. Below is a brief explanation of what each key means: medium - The notification medium: sms or email

Hermes is Konga's in-house notification service – Notifications-as-a-Service (NaaS). It provides a simple RESTFul API for sending notifications; emails and SMS. Tweet

name - The name of a template. Since we send different notification depending on an action, grouping these actions into templates makes a lot of sense. Template names are typically synonymous with actions: shipped_order, order_received, etc.

recipient - the recipient of the notification.
subject - Subject of the email. Not required for SMS.
sender - Sender’s email.
sender_id - Name of the sender.
params - Holds nested JSON that the templates render into real content. Every template has a variable that gets replaced with a key in params.
customer_name - Name of a customer.
order_number - Order number.

While every key in the above payload is mandatory, the keys that form the params varies based on the template content. A template is an HTML document with Jinja2 template syntax.

<!DOCTYPE html>  
<html lang="en">  
<head>  
    <meta charset="UTF-8">
    <title>Title</title>
</head>  
<body>  
    Dear *{customer_name*}* <br/>
    Your order with number: *{order_number*}* has been shipped.
</body>  
</html>  

The above payload plus the template will translate to an email like this:

Dear James Bond,

Your order with number: R123456789 has been shipped.  

Hermes Technology Stack

Hermes is built with the Python Flask framework and it Jinja2 for templating. It uses RabbitMQ for messaging queue, MySQL as its primary data store, Redis for caching and Celery for distributed task queue.

"We have been running Hermes for about 2-years now and it handles millions of notifications monthly."

I'd love to hear from you.

Cover Image, Physical Notifications | Johan Larsson

Celestine Omin

About Celestine Omin

Software Engineer at Konga, VC backed e-commerce in Nigeria. Lead maintainer and developer of NSEFinance, an experimental API for the Nigerian Stock Exchange. Convener of The Lagos GitHub meetup

Comments