Example: job creation with webhook

Last updated 8 months ago

This example will demonstrate a complete manual process of creating a job and receiving the create event over a registered webhook.

1. Registering a webhook

Set up a webhook on your server or create a temporary webhook URL using a third party service. You can use the endpoints described on the receiving job updates page to register your webhook to receive job events. One webhook is enough to receive all necessary job updates. Do not register new webhooks every time you create a job. Here is an example curl that registers a webhook:

curl 'https://prod-api.spatula.io/v2/graph/role/webhooks?access_token=YOUR_TOKEN_HERE' --data '[{"target": "https://example.com/some-test-webhook", "event": "role/jobs"}]'

If your webhook URL and API token are valid the request will be successful and return a 200 series response. You will be able to view your newly created webhook at the webhook list URL for your token. This can be viewed in your browser by replacing "YOUR_TOKEN_HERE" with your Spatula API token in the following link:

https://prod-api.spatula.io/v2/graph/role/webhooks?access_token=YOUR_TOKEN_HERE

2. Create a test job

To create a test job, follow the instructions on the creating jobs page. Here is an example curl to create a job:

curl 'https://prod-api.spatula.io/v2/graph/role/jobs?access_token=YOUR_TOKEN_HERE' --data '[{"name":"Test Job","contact":{"name":"Test Customer","email":"","phone":"+61 234 567 890"},"tasks":[{"zone":{"address":"De Bruns, Castleknock, County Dublin, Ireland","radius":50,"coords":{"lat":53.3728199,"lon":-6.360328900000013},"name":"Arrive @ De Bruns"}},{"zone":{"address":"De Bruns, Castleknock, County Dublin, Ireland","radius":50,"coords":{"lat":53.3728199,"lon":-6.360328900000013},"name":"Depart"}},{"zone":{"address":"Phoenix Park, Dublin, Ireland","radius":50,"coords":{"lat":53.3578178,"lon":-6.334499800000003},"name":"Drop off @ Phoenix Park"}}]}]'

A successful request will result in the endpoint returning a 200 series response with the newly created job object. Here is an example response body corresponding to the curl above:

{
"items": [
{
"id": 1234567890,
"name": "Test Job",
"contact": {
"phone": "+61234567890",
"name": "Test Customer",
"email": ""
},
"tasks": {
"items": [
{
"zone": {
"address": "De Bruns, Castleknock, County Dublin, Ireland",
"name": "Arrive @ De Bruns",
"coords": {
"lon": -6.3603289,
"lat": 53.3728199
}
}
},
{
"zone": {
"address": "De Bruns, Castleknock, County Dublin, Ireland",
"name": "Depart",
"coords": {
"lon": -6.3603289,
"lat": 53.3728199
}
}
},
{
"zone": {
"address": "Phoenix Park, Dublin, Ireland",
"name": "Drop off @ Phoenix Park",
"coords": {
"lon": -6.3344998,
"lat": 53.3578178
}
}
}
]
}
}
]
}

The idfield on the job object should be saved for use in later requests. In JavaScript, the id field of a new job might be extracted using the following code:

responseJson.items[0].id

3. Confirm your webhook received the creation event

At the point of job creation your webhook will receive POST request containing the new job. Here is an example of the webhook request:

{
"type": "create",
"items": [
{
"id": 1234567890,
"name": "Test Job",
"contact": {
"phone": "+61234567890",
"name": "Test Customer",
"email": ""
},
"tasks": {
"items": [
{
"zone": {
"address": "De Bruns, Castleknock, County Dublin, Ireland",
"name": "Arrive @ De Bruns",
"coords": {
"lon": -6.360328900000013,
"lat": 53.3728199
}
}
},
{
"zone": {
"address": "De Bruns, Castleknock, County Dublin, Ireland",
"name": "Depart",
"coords": {
"lon": -6.360328900000013,
"lat": 53.3728199
}
}
},
{
"zone": {
"address": "Phoenix Park, Dublin, Ireland",
"name": "Drop off @ Phoenix Park",
"coords": {
"lon": -6.334499800000003,
"lat": 53.3578178
}
}
}
]
}
}
]
}