Create webhooks (API)

Introduction

After getting familiar with the events available on the UP42 platform, you can start building your own webhooks. Depending on your use case, you can be notified everytime a job task changes its status or check whether a placed order has been successfully completed or not.

Learn more

If you want to dive deeper into configuring and using webhooks, please read our API reference.

Customize webhook

Create a new webhook by inserting the webhook parameters as JSON format in the request body. The parameters are explained in the table below.

Parameter	Definition	Required	Example
`url`	Unique URL where the webhook will send the message (HTTPS is required)	yes	`"https://my.sample.endpoint.com/job"`
`name`	Webhook name	yes	`"my job alerting system"`
`secret`	The secret is a string used to add a signature to the HTTPS request that is sent to the specific URL. The signature will be part of the HTTPS headers. If no secret is added, there will be no signature header. Using a secret has the following advantages: the recipient is informed about the author of the received HTTPS request and can validate the request integrity (i.e. if the data payload is the original or it got modified).	no	`"QWZTFnMEXhqZKNmu"`
`active`	Webhook status (active/inactive)	yes	`true`
`events`	Array of one or more event types (job task status/order status)	yes	`"job.status"` `"order.status"`

In this example (saved in the file webhooks_request.json), the webhook will be triggered every time a new job runs on the defined workspace.

{
   "url": "https://my.sample.endpoint.com/job",
   "name": "my job alerting system",
   "secret": "longRandomStringUsedForSigningPayloads",
   "active": true,
   "events": ["job.status"]
}

Create webhook

Create the webhook by making the following API call:

curl -s -L -X POST -H "Authorization: Bearer $PTOKEN" \
-H 'Content-Type: application/json' \
https://api.up42.com/workspaces/0cb1eaa0-89a3-11ec-a8a3-0242ac120002/webhooks  \
-d @webhooks_request.json | jq '.'

Example response body:

{
   "data": {
       "id": "1df1ebb0-78a4-55d9-b806-15d22e391bd3",
       "url": "https://my.sample.endpoint.com/job",
       "name": "My job alerting system",
       "active": true,
       "events": [
           "job.status"
       ],
       "createdAt": "2022-02-17T08:47:11.377149Z",
       "updatedAt": "2022-02-17T08:47:11.377149Z",
       "secret": "longRandomStringUsedForSigningPayloads"
   },
   "error": null
}

Test webhook

Test the newly-created webhook based on the webhook ID generated during the last API command.

curl -s -L -X POST -H "Authorization: Bearer $PTOKEN" \
-H 'Content-Type: application/json' \
https://api.up42.com/workspaces/$workspace_id/webhooks/$webhook_id/tests \
-d '{"eventNames": ["job.status"]}' | jq '.'

Example response body:

{
   "data": {
      "startedAt": "2022-02-18T15:12:18.668452Z",
      "testsRun": 1,
      "testsSucceeded": 1,
      "testsFailed": 0,
      "tests": [{
         "startedAt": "2022-02-18T15:12:19.362725Z",
         "eventName": "job.status",
         "success": true,
         "message": "Test request was successful!",
         "request": {
            "headers": {
               "caseInsensitiveName": true,
               "empty": false
            },
            "body": {
               "event": "job.status",
               "liveMode": false,
               "messageId": "377669ea-5521-416a-976a-8e290466f7fb",
               "timestamp": "2022-02-18T15:12:18.672945Z",
               "body": {
                  "jobId": "FB0DA199-01DF-4635-910D-A823AE7DC200",
                  "status": "PENDING",
                  "tasks": 
                    [{
                      "id": "FB0DA199-01DF-4635-910D-A823AE7DC201",
                      "status": "NOT_STARTED",
                      "startedAt": null,
                      "finishedAt": null
                     },
                     {
                      "id": "FB0DA199-01DF-4635-910D-A823AE7DC202",
                      "status": "PENDING",
                      "startedAt": "2021-12-21T10:14:37Z",
                      "finishedAt": null
                     }],
                  "startedAt": "2021-12-21T10:14:27Z",
                  "finishedAt": null
               }
            }
         },
         "response": "HttpResponse[https://my.sample.endpoint.com/job, 200 OK]"
      }]
   },
   "error": null
}

Trigger webhook

The next step is to perform an action defined by one of the two events and trigger the webhook. In this example, you will run a job. When the job run starts, the webhook will send a payload to the webhook URL of the recipient. The example below shows the payload for a job status:

{
"event": "job.status",
"liveMode": true,
"messageId": "8e3bfae9-ac06-4a0a-beae-653b2d56f69f",
"timestamp": "2022-04-05T12:46:17Z",
"body": {
   "id": "a04c1abe-ff2b-4942-8584-daff733da98d",
   "status": "RUNNING",
   "startedAt": "2022-04-05T12:46:01Z",
   "finishedAt": null,
   "tasks": [{
   "id": "807a3121-bd8f-4671-8c2d-f70663d80e92",
   "status": "RUNNING",
   "startedAt": "2022-04-05T12:46:11Z",
   "finishedAt": null,
   "logUrl": "https://api.up42.com/projects/{project_id}/jobs/{job_id}/tasks/{task_id}/logs"
      }]
   }
}

Congratulations! You have successfully created a webhook that will alert you each time a job run starts and each time the task status changes.