Webhooks in SAP Sales and Service Cloud V2

[JoEng]

SAP Sales and Service Cloud V2 is providing different functions to tailor the behavior of the applications to your  needs. Especially Determinations, Validations and Autoflows allows you to create rules, based on changes to objects in the system. The build in capabilities are by purpose limited, to have a clear separation between configuration and custom code. If the intended scenario is exceeding the build in functionality, SAP Sales and Service Cloud V2 is providing webhook based extensions points for custom code.

In this article we will discuss the general functionality of the webhooks and how to the open architecture is providing you the flexibility to meet your corporate requirements.

Webhooks

In SAP Sales and Service Cloud V2, we distinguish between async and sync wekbhooks. Synchronous webhooks are intercepting the operation, and providing the capability to react or change direct user input. Async webhooks are called after the operations is finished. They allow to trigger processes on changed data. E.g. informing a 3rd party system about an updated data set. It is important to keep in mind, sync webhooks are blocking the execution of a request. That way they are impacting the performance of the system. To avoid a negative impact, we recommend to leverage as much as possible async processing. Scenarios vor sync webhooks could be complex validations on user input or determinations, changing data on the same object, which would otherwise cause blocking write requests.

In this blog post we will focus on sync webhooks. You can find a simple example of an async webhook on github.

Architecture

The architecture is very simple. At the end we need to expose a webservice endpoint on the internet, so it can be called by SAP Sales and Service Cloud V2. We will deploy a simple nodejs service on SAP BTP CloudFoundy Runtime exposing a HTTP Post endpoint on /path.

Implementation

The Service is written in NodeJS and will expose a POST endpoint on /case. 

const express = require('express')
var app = module.exports = express();
app.use(express.json());

console.log("Start....")

app.post( '/case', function ( req, res) {
    console.log(JSON.stringify(req.body))
    res = res.status(200);
    res = res.type('application/json');

    let beforeImage = req.body.beforeImage
    let data = req.body.currentImage

    data.extensions = data.extensions || {}
    if (data.serviceTeam &&
        beforeImage.serviceTeam &&
        data.serviceTeam.id != beforeImage.serviceTeam.id) {
            delete data.processor
    }    
    let body = {
        data: data
    }
    res.send(body);
})



if (!module.parent) {
    app.listen( process.env.PORT || 4000)
    console.log('Express started....');
}

app.js

SAP Sales and Service Cloud V2 will call this endpoint and send a json structure containing a before and a current image of the object. In the service we compare if the processing team of the case has changed. Only if the team has changed, we will remove the current processor from the case, to make sure a processor of the new team can pick the case. As response, the new "adjusted" object is returned as part of the data attribute in the response json.

{
    "name": "sync-webhook",
    "version": "0.0.1",
    "main": "app.js",
    "scripts": {
        "test": "mocha",
        "start": "node app.js"
    },
    "dependencies": {

        "express": "^4.18.2"
    },
    "devDependencies": {
        "expect.js": "^0.3.1",
        "axios": "^1.7.8",
        "mocha": "^10.8.2",
        "supertest": "^7.0.0"
    }
}

package.json

To speed up the development of extensions I recommend to follow a Test-Driven-Development (TDD) approach. This will allow local development and testing before deploying the changes and testing manual in SAP Sales and Service Cloud V2. On the long run, this approach will also help to keep the quality of the system high.

var request = require('supertest')
  , app = require('../app');
var expect = require('expect.js');




let url;



describe('Test Case Wekhook', () => {
    it('Removes Processor on team change', (done) => {
        var testRequestBody = {"entity":"sap.crm.caseservice.entity.case",...}
        request(app)
        .post('/case')
        .send(testRequestBody)
        .expect('Content-Type', /json/)
        .expect(200)
        .then( response => {
            expect(response.body.data.processor).to.be(undefined)
            done()
        })
    })
    it('Keeps Processor on team change', (done) => {
        var testRequestBody = {"entity":"sap.crm.caseservice.entity.case"...}
        request(app)
        .post('/case')
        .send(testRequestBody)
        .expect('Content-Type', /json/)
        .expect(200)
        .then( response => {
            expect(response.body.data.processor.id).to.be('11ecc541-6e89-4fbe-afdb-81e430a8c000')
            done()
        })
    })
})

case.test.js

With the simple test above, I can quickly validate if the service code is behaving in the expected way. I can also include additional scenarios and test them without the need to deploy the service.

Deployment and Operations

The entire service can be simply deployed to SAP BTP CloudFoundry. As the tool itself is very simple the requirements for the App are not very high. Without further testing, it is safe to run the app with 128MB Memory. Independent from the technology, it is recommended, to deploy at least 3 instances of the app. This will ensure one active instance even during an error or cluster event.

---
applications:
- name: sync-webhook
  command: node app.js
  instances: 3
  memory: 128M
  default-route: true
  buildpack: nodejs_buildpack
  env: 
    OPTIMIZE_MEMORY: "true"

manifest.yml

Please keep in mind, the application is blocking requests to the related object on SAP Sales and Service Cloud V2. This includes, if there is an problem with the app, all users of the tenant are impacted. For this reason it is recommended to include the application in the central monitoring and operations. 

The benefit of the side-by-side approach, it provides you many more feature to control and monitor the behavior of your extensions. This comes especially handy, if you need to understand the performance impact of an extension. In CloudFoundry it is possible to retrieve the access log with a simple cf logs. A first look at the response-time metric will give you an inside, how fast your custom code is responding to requests. A more sophisticated solution with detailed insides would be a Application Performance Management (APM) tool, which can help you to find any bottle neck.

Registering the Webhook 

To enable the Webhook in SAP Sales and Service Cloud V2, we need to create a outbound communication system, which is pointing to the host of our webservice. In our case, we will use the application Domain assigned by CloudFoundry. Please be aware, it is recommended to secure the endpoint. If no personal data is stored in the webhook, a simple protection via Basic Auth will be sufficient. If personal data is involved higher measures might be required.

In the second step, the webhook can be configured at the root object. In our case, we are adding the webhook to the case object. In general the Webhook should be configured as pre-hook. Pre-hooks are executed before the core validations and determinations. That way, we are able to change all fields. In the post hook, since the standard validations are already executed it is only possible to change extension fields.

After the webhook is successfully registered, we can test it. For testing open a case, with a team and a processor assigned. As soon as the team is changed, the processor will be removed from the case.

Summary

Webhooks are a very power full tool, to include custom code in SAP Sales and Service Cloud V2. The possibilities are close to endless. Beside simple rule based extensions, complex AI/ML scenarios or scenarios with 3rd party tools are possible. Nevertheless, with great power comes great responsibilities. As Sync-Webhooks are executed during a call to the SAP Sales and Service Cloud V2 API they have a direct impact on the performance of the system. To ensure a high performance additional measures like caching might be recommended. Due to the open architecture of SAP Sales and Service Cloud V2, it is possible to choose the right architecture, which is not only solving the technical requirements but also fitting to the strategy of the company. Instead of using Node JS and Cloud Foundry it would be possible to use e.g. Kyma and Java or to deploy directly to a hyperscaler. Only requirement is, the endpoint must be available through the internet and listen to HTTP Post requests. That way, the SAP Sales and Service Cloud V2 implementation can be tailored to the needs and strength of the company.

Resources

• Getting started on BTP CloudFoundry 
• Async Webhook Example
• External Hooks Documentation
• Pro-code UI Extension in SAP Sales and Service Cloud V2
• Sample Code