Skip to Content
Technical Articles

Cloud Foundry Enterprise Messaging Webhooks 📨

Hi Community!

I would love to share this blog with you guys about “Cloud Foundry Enterprise Messaging Webhooks 📨”. This because it is an “easy” solution to get real-time messaging events from wherever you want to wherever you desire. When I say real-time, I’m talking about Webhooks, web-sockets and so on, no polling and pulling!

This will be a Blog series with the following topics in separated Blog posts:

Cloud Foundry Enterprise Messaging Webhooks 📨 (this blog)
Send AMQP messages from CPI to Enterprise Messaging and Consume them in a Node.js AMQP Application 📨
WebSocket’s in SAP UI5 Multi Target Applications consuming Enterprise Messaging 📨

 

Introduction

First things first, this blog is not going to be about “What is Enterprise Messaging” or “How to get started with enterprise messaging”. To get started and go all the way I would really recommend having a look at the SAP Help Documentation:

https://help.sap.com/viewer/bf82e6b26456494cbdd197057c09979f/Cloud/en-US

It is the best way to setup, get started and make some advanced cool demo app/projects.

It is also the way I started to discover and get hands on with this Enterprise Messaging service in Cloud Foundry.

Now why this blog? Because I love real-time data in my applications, and I hate the pulling/polling implementations in applications. It is a bad practice and it can result in a lot of overheat and bad user experience. In short, your application will not be the best it can be.

It actually also makes a lot of sense to use Webhooks and or WebSocket’s. Let me clarify this “common sense” by the following example:

Imagine you are desperate for that one book in the library. But sadly enough someone else borrowed the book before you and did not yet return it. You do not want to go back to the library every single day over and over again. Cause this would be the pulling/polling effect. What you do want to achieve, is a scenario where the library staff members contact you once the book has been returned. This can be compared to the Webhooks/WebSocket’s implementation. Just “common sense” between the server and the client, like the customer and the library.

 

Webhooks <> WebSocket’s

Now before we start the setup of our Enterprise Messaging Webhook, it is important to understand the difference between Webhooks and WebSocket’s. I did some Googling myself and I found the following explanation on Stack Overflow.

Which gives you a good and nice idea on how these technologies work and how they differ from each other.

Webhooks

Webhooks are for server to server communication. They work by one server telling another server that it wants data sent to a certain URL when something happens.

WebSocket’s

WebSocket’s are (usually) for server to browser communication. The server hosts a WebSocket server, and clients can open a connection to that server. This is popular now mostly because it is faster and less resource-hogging than older ways of solving the problem like long-polling.

 

Setup the Enterprise Messaging Queue

To setup your Enterprise Messaging and Environment you can check out the following SAP Help Documentation:

https://help.sap.com/viewer/bf82e6b26456494cbdd197057c09979f/Cloud/en-US/3ef34ffcbbe94d3e8fff0f9ea2d5911d.html

Let’s say I have the following Queue inside my Enterprise Messaging Cockpit called “ErrorQueue”.

 

Send a Message to the Queue

To send messages to Queues you can check out the following SAP Help Documentation:

https://help.sap.com/viewer/bf82e6b26456494cbdd197057c09979f/Cloud/en-US/577ea7ce5cef4e2ea974c03d5549b3ff.html

Which will also point you to the API-Endpoint documentation:

https://help.sap.com/doc/3dfdf81b17b744ea921ce7ad464d1bd7/Cloud/en-US/messagingrest-api-spec.html

Let’s say I send the following message to my “ErrorQueue”:

{
    "errorMessage": "This error came from Postman!"
}

This HTTP-POST-Request will create the message above inside our “ErrorQueue” Queue. It will return the HTTP-status-code “204 No Content” when successful.

When you perform a GET request to retrieve all your Queues, you will get a result like this:

If you have a look at your “ErrorQueue” inside the Enterprise Messaging Cockpit, you will also see the number of messages inside the Queue.

 

Building a Node.js Webhook

If you have a look at the Webhook definition above, you see that you need a second server. Wait where is my first one? Well, this is the Enterprise Messaging Service itself. It is able to receive message/notifications via REST, MQTT and AMQP, which means it is also possible to send messages via those protocols to the Enterprise Messaging Queues and Topics. But there are some “Prerequisites and Restrictions” in receiving and sending messages, which can be found here:

https://help.sap.com/viewer/bf82e6b26456494cbdd197057c09979f/Cloud/en-US/ac83090b07684f8e908df40d024f8fe5.html

In the end it is no more than the Enterprise Messaging Server performing a POST-request on the URL you provided as Webhook.

This means we need to provide an Endpoint inside our Node.js Application which allows us to perform a POST request. We will use “Express” to build such a server and to expose our endpoints.

To build a Node.js Application and deploy it to Cloud Foundry you can follow the following SAP Help documentation:

https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/772b45ce6c46492b908d4c985add932a.html

Inside the “index.js” file you add an endpoint called “/emMessages” and you make sure it is an endpoint which allows us to perform a POST-request on.

In the end your code will look like this:

const express = require('express');
const app = express();
const bodyParser = require('body-parser');

// support parsing of application/json type post data
app.use(bodyParser.json());

//support parsing of application/x-www-form-urlencoded post data
app.use(bodyParser.urlencoded({
    extended: true
}));

app.get('/', function (req, res) {
    res.send('Hello World!');
});

app.post('/emMessages', function (req, res) {
    console.log(JSON.stringify(req.body));
    res.status(201).send();
});

const port = process.env.PORT || 3000;
app.listen(port, function () {
    console.log('App listening on port ' + port);
});

As you can see the “body-parser” package is required and used on our “app” (express server). This allows us to read the payload from the POST-request.

Once we receive the data on this “/emMessages” endpoint, we log to the console.

With this you finished the development of your Webhook for the Enterprise Messaging. You deploy this application to your SAP Cloud Foundry Space with the following command:

cf push

Just like it is explained in the SAP Help documentation above.

With this you deployed your Webhook and you can configure it in the SAP Enterprise Messaging Cockpit.

 

Setup the EM Webhook Subscription

With the Node.js App deployed, which fulfills the role of a Webhook, we are ready to use this app inside the Enterprise Messaging Cockpit. But first the Webhook URL needs to be retrieved. Go to your SAP Cloud Foundry Space Applications and select your Webhook App.

Once you selected the Webhook app, you will see the URL.

Copy paste this URL since you will need it in the Enterprise Messaging Cockpit Webhook Subscriptions” configuration panel.

In the Enterprise Messaging Cockpit under the “Webhook Subscriptions” a new configuration needs to be created. This with the following configuration values:

Configuration table for the input fields above:

Config

Value

Subscription Name Free to choose
Queue Name Queue you want the Webhook the subscribe to. In this case “ErrorQueue”.
Quality of Service (QoS) 0 (No acknowledgement has to be sent after consumption this way)
Webhook URL The URL of you Webhook in CF. (You just copied it) It needs to start with https:// followed by the URL and it ends with the “/emMessages”. This because that is the endpoint which was implemented to receive the messages.
Exempt Handshake YES (we do not need the handshake acknowledgments between our Webhook app server and Enterprise Messaging)
Authentication NoAuthentication (Since no authentication method was provided inside the Node.js App, could be OAuth2 with passport and xsuaa)

Once you created the “Webhook Subscription” it will appear in the overview:

 

Examine messages in the Node.js Webhook

At the moment there is still one message in the “ErrorQueue”, because it was sent to the Queue before the Webhook was created. But Enterprise Messaging picked up this message and sends it over to the Webhook URL once created. Depending if your Webhook was already up and running, the message will be logged or not.

Resend the message with the following payload to the Enterprise Messaging “ErrorQueue”:

{
    "errorMessage": "This error came from Postman!"
}

Have a look at the Node.js Webhook Application in the SAP Cloud Foundry Space. Select the Application and choose the “Logs” section in the left-hand-side menu.

As you can see the message has been logged inside the Node.js application.

 

Wrap up 🎁

With this setup, configuration and development, you created a Node.js Webhook application for the Enterprise Messaging Service and you subscribed your Queue to it. A Webhook is no more then an endpoint which allows you to perform an HTTP-POST request on. This is exactly what the Enterprise Messaging does, once a Webhook Subscription has been configured. It receives messages and it “forwards” it to the Webhook endpoint.

In the next blog we will have a look at “Send AMQP messages from CPI to Enterprise Messaging and Consume them in a Node.js AMQP Application 📨”. I hope you found this blog helpful and interesting and I’ll see you in the next blog!

Kind regards,

Dries

13 Comments
You must be Logged on to comment or reply to a post.
  • Hello Dries,

    is it possible to get X-Message-Id when receiving an event from Webhook?

    So that an acknowledgement can be provided.

    My requirement is to keep the message in Unacknowledged Queue, if the downstream application is down during maintenance.

    Thanks,

    Varun

    • Hi Varun,

      Thanks for your good question!

      To be honest I had no idea, I had a look at it myself and at the moment I did not find an answer for your question.

      I do not see the X-Message-Id neither when I consume the messages via another Node.js app using @sap/xb-msg and not webhooks.

      Also when I create a webhook in the Enterprise Messaging Dashboard and i set the QOS to 1 while I send a message with x-qos to 1 the message is still consumed and no longer present in the queue.

      I would expect it to be still present in such a case since the acknowledgement is still to send, but it is totally consumed.

      What you could do, but I do not recommend and always try to avoid it is to create an application that polls the the messages via the rest API-endpoint and then sends the acknowledgement after reading the headers. But that just sounds very bad and I believe there should be another way to find out that  X-Message-Id, but I can’t tell how for the moment.

      Good luck!

      Best regards,

      Dries

       

  • Dries Van Vaerenbergh Thanks for sharing such informative article. I am not able to access  YouTube playlist mentioned  at the start of the blog. Also, i am not able to access the YouTube videos embedded into this blog. I am just wondering if you have removed these videos or it is something related to my account only? Can you please share updated URL?

     

     

    YouTube%20Video%20Error

    YouTube Video Error

     

    YouTube%20Playlist

    YouTube Playlist

     

    • Hi Khurram Mir thanks for your feedback and to inform me about the videos.

      I just checked it out myself and the videos are put privately it seems or they have been removed.

      The videos are not mine, I only referred to the SAP HANA Academy their tutorial videos since they were really informative and nice to get started with Enterprise Messaging.

      I will try to update the blogs by replacing the videos with the SAP Help documentation.

      Once done, I will tag you in these comments again.

      In the meanwhile you could have a look at the following live stream replay where we also send messages to a queue:

      https://www.youtube.com/watch?v=DKI2WgDS_k0

      Thanks for the update!

      Best regards,

      Dries