Salesforce - GitHub integration using Webhook

Salesforce supports webhooks for communicating with many other applications. In this post let us see how we can use webhooks to communicate between Github and Salesforce to track details of push event.

1. What is Webhook

In Salesforce, we can define what action should happen when a specific event occurs. Triggers and flows can define before and after actions. Similarly, other applications provides event actions called webhooks, which is basically an HTTP POST to external URLs, which are registered under specific event actions.

There are multiple applications that currently support webhooks. Github, JIRA, ServiceNow, Twilio, Whatsapp are some examples. 

These applications can register multiple subscribers for the same event, thus passing the same message to multiple systems when some event is happening.

2. How to create a Webhook supported URL in Salesforce

In Salesforce creating a webhook supported URL involves the below steps:

1. Create Apex REST API

First, create a new Apex REST API Class as shown below, later we can add logic to that based on the subscribed webhook.

take a note of the url mapping - @RestResource(urlMapping='/api/Webhooks/incoming/pushDetails/*')

2. Create a public Site

In salesforce, we need to create a public site if we need to explore the above apex class to a webhook event. So let us create a new public site as shown below and keep the default setting:

3. Enable Apex class Access to the site

Once the site is saved, click on "Public Access Settings" button on site, which will take you to the profile associated with the site guest user.Edit the Enabled Apex Class Access and add our newly created class to the list.

3. GitHub Webhook Details

1. Create a new repository

To start with understanding more details about GitHub webhooks, let us create a new repository first.

2. How to access Webhooks

Under the newly created repository, go to settings and you can see WebHooks.

3. Create a new Webhook adding Salesforce as Subscriber

Click on Add Webhook button, and populate details:

1. payload URL - <Sitedomain>/services/apexrest/<rest urlmapping>

https://meerademosite-developer-edition.ap17.force.com/services/apexrest/api/Webhooks/pushDetails

2. Content type - Application/json

3. Secret - keep it empty for now, we can add this later

4. SSL verification - keep Default

5. Which events would you like to trigger this webhook? - Just the push Event

6. Active - true

And complete the action by clicking on Add Webhooks button.

In addition to Push activity, GitHub supports webhook for the below events also:

4. Request processing in Apex

Before processing this in Apex, you can find a sample payload for Push event in Github Documentation

When a push event is happening we would like to get the below details in Salesforce processing the payload:

1. Committer name

2. Commiter Email

3. Committer Comment

4. Committed Time

5. Committed url

6. Repository name

7. Added Components

8. Removed Components

9. Modified Components

To store these details, first, let us create a custom object - GitHub_Push_Details__c with the above fields. 

Now update logic inside Apex class to parse the response and retrieve required details. 

As an example let us see how to retrieve committer name and email from payload.

"pusher": {

    "name": "MeeraRNair",

    "email": "m*********@****.com"

  },

To get this we can define an inner class:

And now parse the request and retrieve details as shown below:

Similarly we can retrieve other required details also. Once this is retrieved, we can create a record of GitHub_Push_Details__c  and insert it.

You can also see setting response. The complete logic is uploaded here.

Now from VS code, connect to newly created repo by:

git remote add origin https://github.com/MeeraRNair/WebhookDemo.git

And push the class to repository:

In webhook details in GitHub, you can see that webhook got published successfully.

Request:

Response:

If our class processed request successfully, you can see a new record in GitHub_Push_Details__c :

Record Detail View:

So this approach will help us to see the push details in Salesforce itself without logging into GitHub.

5. How to make this more secure

The problem with public site is that any one with this URL will be able to post data to salesforce and that will get processed. How we can add additional security to this communication?

GitHub provides an option to add  Secret key to the Webhook set up. We can refer this link to get additional details on this.

How this secret will work?

When we add a secret,Github will hash the payload using the provided secret, using HMAC hex digest and hashed value will be added to the header as shown below:

Now we can modify our Apex class to validate this hashed header compoenent. Use methods provided by Crypto class to hash the body of payload using the same secret, and compare that value with the one we received at request header.

Code:

if the authentication fails, we can set corresponsing status code and message in the response:

Also in webhook sender, we can see the error:

You can watch a short Demo here:

References:

https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#push

https://docs.github.com/en/developers/webhooks-and-events/webhooks/securing-your-webhooks