Establishing webhooks
This chapter demonstrates how to set up webhooks for Skedulo using the Skedulo Lens API and ngrok, which is a useful tool for locally testing and viewing webhook responses.
About ngrok
For development purposes, this chapter uses ngrok to establish a secure HTTP tunnel to a server running on your local machine.
Skedulo only permits HTTPS URLs for webhooks.
Prerequisites
- You must have an API user configured in your Skedulo organization. See Skedulo API user for more information.
- You have a valid API access token and have configured this as an environment variable. This example uses
$AUTH_TOKEN
to represent the API authentication environment variable. - Node/NPM is installed.
- (Optional) jq is installed.
This example uses .json
files executed using cURL commands for readability and simpler query creation
Create a webhook
- Create and open a
webhooks
folder from the terminal:$ mkdir webhooks && cd webhooks
- Download and install ngrok in the
webhooks
folder:- Go to https://ngrok.com/ and click Download.
- Download the version of ngrok for your operating system.
- Unzip ngrok into the
/webhooks
folder.
Create a file called
httpserver.js
with the following configuration:const http = require("http"); http.createServer((req, res) => { const body = []; req .on('data', (chunk) => { body.push(chunk); }) .on('end', () => { const bodyStr = Buffer.concat(body).toString(); const obj = { headers: req.headers, body: JSON.parse(bodyStr) } console.log(JSON.stringify(obj, null, 2)) res.write(JSON.stringify(obj, null, 2)) res.end() }); res.writeHead(200, {"Content-Type": "application/json"}) }).listen(8080)
4. Start the HTTP server in one terminal: node httpserver.js
5. Start ngrok in another terminal:
./ngrok http 8080
Take note of the HTTPS address of your ngrok server. For example: https://b14b2804.ngrok.io
6. In another terminal, create a file called webhook.js
. This is just so you can create your queries in a readable way. It’s not necessary if you want to just send your JSON queries using a cURL command. Add the following content to your webhook.js
file, using the HTTPS ngrok server address as the url
.
const url = "https://b14b2804.ngrok.io"
const json = {
name: "test",
url: url,
type: "graphql",
query: `
subscription {
schemaJobs {
operation
timestamp
data {
UID
Duration
}
previous {
Duration
}
}
}
`
}
console.log(JSON.stringify(json, null, 2))
- One of the fields in the
data
block needs to change to call the webhook. In this case, this includesUID
andDuration
. - The
schemaJobs
field also acceptsfilter
andextendedFilter
parameters. - The
operation
parameter can be used to ignore events that do not have the operation value. Theoperation
parameter accepts an array of values:INSERT
,UPDATE
orDELETE
.
7. Create a webhook request body:
node webhook.js > temp.json
8. Create a POST
request to the Skedulo API that references the temp.json
file containing the GraphQL subscription request:
curl -s -X POST -H "Authorization: Bearer $AUTH_TOKEN" -H "Content-Type: application/json" -d @temp.json 'https://api.skedulo.com/webhooks' | jq
This returns the following response in the terminal:
{
"result": {
"id": "9849cceb-c426-488b-89dc-6ff02b33802d",
"name": "test",
"url": "https://b14b2804.ngrok.io",
"headers": {},
"query": "\n subscription {\n schemaJobs {\n operation\n timestamp\n data {\n UID\n Duration\n }\n previous {\n Duration\n }\n }\n }\n ",
"customFields": {},
"type": "graphql"
}
}
9. Create a new job using a GraphQL query.
The following response should appear in the terminal window that is listening on port 8080
:
{
"headers": {
"user-agent": "Skedulo-Webhook",
"skedulo-webhook-id": "9849cceb-c426-488b-89dc-6ff02b33802d",
"skedulo-request-id": "317cc297-c9cb-41e5-a741-366b3724cb8e",
"content-length": "182",
"content-type": "application/json; charset=UTF-8",
"accept-encoding": "gzip, deflate",
"host": "b14b2804.ngrok.io",
"accept": "*/*",
"x-forwarded-proto": "https",
"x-forwarded-for": "34.215.60.60"
},
"body": [
{
"data": {
"schemaJobs": {
"data": {
"UID": "00145d1e-974a-4f97-9cd7-7cd280f824a8",
"Duration": 60
},
"previous": {
"Duration": 60
},
"operation": "INSERT",
"timestamp": "2019-07-02T03:29:35.969Z"
}
}
}
]
}
You can also view the webhook trigger request responses in the local ngrok web interface.
10. Update a job to change the Duration
to 30
. The response displays in the terminal:
{
"headers": {
"user-agent": "Skedulo-Webhook",
"skedulo-webhook-id": "9849cceb-c426-488b-89dc-6ff02b33802d",
"skedulo-request-id": "fdf22ac0-b6d5-4453-9bfa-9735c7e2cdde",
"content-length": "182",
"content-type": "application/json; charset=UTF-8",
"accept-encoding": "gzip, deflate",
"host": "b14b2804.ngrok.io",
"accept": "*/*",
"x-forwarded-proto": "https",
"x-forwarded-for": "34.215.60.60"
},
"body": [
{
"data": {
"schemaJobs": {
"data": {
"UID": "00145d1e-974a-4f97-9cd7-7cd280f824a8",
"Duration": 30
},
"previous": {
"Duration": 60
},
"operation": "UPDATE",
"timestamp": "2019-07-02T03:31:27.970Z"
}
}
}
]
}
11. A record of the HTTP request appears in the terminal tab that is running ngrok:
The ngrok web interface also shows both of the operations and responses:
Retrieve webhooks
You can retrieve webhooks that are currently set up for your tenancy using the following cURL command:
curl -s -X GET -H "Authorization: Bearer $AUTH_TOKEN" https://api.skedulo.com/webhooks
Because I still have both the test
and test_deferred
webhooks active, the response returns both webhooks:
{
"result": [
{
"id": "9849cceb-c426-488b-89dc-6ff02b33802d",
"name": "test",
"url": "https://b14b2804.ngrok.io",
"headers": {},
"query": "\n subscription {\n schemaJobs {\n operation\n timestamp\n data {\n UID\n Duration\n }\n previous {\n Duration\n }\n }\n }\n ",
"customFields": {},
"type": "graphql"
},
{
"id": "6b6d32e0-ad1f-45fa-9f03-b5264ca02ecb",
"name": "test_deferred",
"url": "https://b14b2804.ngrok.io",
"headers": {},
"schemaName": "Jobs",
"fieldName": "CreatedDate",
"offset": 10000,
"filter": "Description != 'cancel'",
"query": "\n subscription {\n jobs {\n UID\n Name\n Description\n Duration\n Start\n End\n CreatedDate\n JobAllocations {\n UID\n }\n }\n }\n ",
"customFields": {},
"type": "graphql_deferred"
}
]
}
Delete a webhook
To delete your webhook when you no longer require the connection, you can delete the webhook using the following cURL command with the webhook id
.
curl -s -X DELETE -H "Authorization: Bearer $AUTH_TOKEN" 'https://api.skedulo.com/webhooks/a0cd6a80-8a9d-4ed5-92f6-9c0e03b6281e'
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.