Creating a Webhook in ServiceNow
In the ever-evolving world of technology, staying connected and ensuring smooth communication between applications is key. This is no different in ServiceNow, where one of the platform's core selling points is its ability to facilitate seamless interaction between systems.
Webhooks can be incredibly useful in ServiceNow. They help automate tasks, keep data up to date, and ensure everything runs like a well-oiled machine.
In this blog, I’ll Walk you through the basics of webhooks in ServiceNow, how to set one up, and how to process the messages you receive from a subscribed webhook.
Contents
- What is a Webhook?
- Creating the Webhook in ServiceNow
- Creating the webhook with your provider
- Making our webhook do some work
What is a Webhook?
A webhook is a way for applications to automatically send data to each other when an event occurs. Imagine you're driving somewhere with kids in the car. Every five minutes, they ask, "Are we there yet?" This is like "polling" in the IT world, where you repeatedly ask a system if there are any updates.
Webhooks eliminate the need for polling by sending an update to your system whenever something changes, so you don't have to keep asking. In our analogy, the kids patiently wait until you turn around and tell them you've arrived or provide any other update about the journey.
For example, consider JIRA. If you have a JIRA ticket and a corresponding incident in ServiceNow, you could either ask every two minutes if anyone has updated the JIRA ticket, or you could configure a webhook to notify you as soon as someone makes an update.
Creating the Webhook in ServiceNow
When I first started looking into webhooks, I'll admit I gave up. I found them a bit confusing and didn't see how they were worth the effort. However, when I was tasked with a bi-directional integration with a third-party provider, I put on my big boy trousers and went for it. And you know what? It was relatively straightforward.
Note: This is all created on my PDI. No security measures or considerations have been included as this is just an example!
First, we need to create an endpoint for the webhook to send events to. You can do this in ServiceNow with a Scripted REST API (SCRAPI).
These can be found in System Web Services > Scripted Web Services > Scripted REST APIs.
Create a new one and give it a name; the API ID is automatically added afterwards.
Next, scroll to the bottom and find the "Resources" related list. Click "New" in the far right corner.
Working with WebHooks
Give it a name, for my example I’m using “POST Webhook” and setting the HTTP Method to POST
Now, although I said I wasn’t going to add any security to my SCRAPI, I’d recommend updating the relative path to be something random. For example, mine is below.
This is a basic way of adding some very minimal security to your webhook. Ideally, your provider should allow you to add headers, which you can use with a configured API Key in ServiceNow.
Anyway, submit your form and make a note of your “Resource path”
Your full endpoint URL will then be
https://YOUR_INSTANCE.service-now.com/api/snc/examplewebhook/WdJKd-1sJi8-KmnoP
In my example I’ve removed security from the “Security” tab under the script field.
In the script, we can add a the following
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
gs.info("Request body is " + request.body.dataString);
// Logging the request we receive so we can take a look!
})(request, response);
And we're done, you can hit submit or save if you've already submitted.
Creating the webhook with your provider
So for this example we're going super simple and using GitHub's webhook capabilities, simply because it's free to create and use.
Some providers will give you and Endpoint and some sample JSON. For example, JIRA gives the following sample JSON
{
"name": "my first webhook via rest",
"url": "http://www.example.com/webhooks",
"events": [
"jira:issue_created",
"jira:issue_updated"
],
"filters": {
"issue-related-events-section": "Project = JRA AND resolution = Fixed"
},
"excludeBody" : false
}
All we would need to change here is the URL to https://YOUR_INSTANCE.service-now.com/api/snc/examplewebhook/WdJKd-1sJi8-KmnoP
Then, using Postman and following JIRAs instructions, send a POST request with the above JSON as your body to the following URL
<JIRA_URL>/rest/webhooks/1.0/webhook
There you have it, the webhook has been created and it's now pointing at the Endpoint we created earlier. Any JIRA issue created or updated, as specified in the "events" in the above JSON, will result in a message being sent to our instance which we can manipulate via the SCRAPI.
Making our webhook do some work
Although in the above example we've used JIRA, for our actual demonstration we're going to focus on GitHub. This is because it's free to use and anyone following this example without a JIRA account can join in.
On GitHub, navigate to the main page of your repository.
Under your repository name, click Settings.
In the left sidebar, click Webhooks and then click Add webhook.
Fill out the Webhook details as follows
Remember, the Payload URL will be different for your instance. It should be something like:
https://YOU_SN_INSTANCE.service-now.com/RESOURCE_PATH
NOTE: Remember to change the content type to "application/json" otherwise you may get a 415 error in response.
Once you click "Add webhook," it should immediately send a Ping to your instance.
And there you have it, you've configured a webhook to communicate with your ServiceNow instance. Now, if we check the logs in ServiceNow, we should see the "Ping" that GitHub sends to test the Webhook.
