Overview
A webhook is a method for sending event notifications from one application to another. When something happens in a source system indicated by an event, the webhook transmits an event notification via HTTPS to a specific URL.
You can also create and manage webhooks using the console.
See notification events
To see all available notification events, call the /webhooks/events endpoint.
Request
GET /webhooks/events HTTP/1.1
Host: api.up42.com
Response
See response example
{
"data": [
{
"name": "job.status",
"title": "Job Status Updates",
"category": "job",
"description": "Sent when job/task status is updated",
"documentation": "https://docs.up42.com/developers/"
},
{
"name": "order.status",
"title": "Order Status Updates",
"category": "order",
"description": "Sent when order status is updated",
"documentation": "https://docs.up42.com/developers/"
}
],
"error": null
}
Parameter | Overview |
---|---|
data.name | string The name of the event. You can set up webhooks to receive notifications for the following status updates: |
data.title | string The title of the event. |
data.category | string The type of events to notify about. |
data.description | string The description of the event. |
data.documentation | string A link to the documentation. |
Create a webhook
To create a webhook, call the /workspaces/{workspace_id}/webhooks endpoint with your workspace ID as a path parameter.
Request
POST /workspaces/{workspace-id}/webhooks HTTP/1.1
Host: api.up42.com
Content-Type: application/json
Authorization: Bearer {token}
Parameter | Overview |
---|---|
events | array of strings / required A list of events that trigger the webhook. |
name | string / required The name of the webhook. |
url | string / required The URL of the webhook. |
secret | string The secret used to generate webhook signatures. |
active | boolean Whether this webhook should be active after creation. The default value is false . |
See request example
{
"events": ["job.status, order.status"],
"name": "My alert for job and order statuses",
"url": "https://my.sample.endpoint.com/",
"secret": "QWZTFnMEXhqZKNmu",
"active": true
}
Response
See response example
{
"data": {
"id": "1df1ebb0-78a4-55d9-b806-15d22e391bd3",
"url": "https://my.sample.endpoint.com/",
"name": "My alert for job and order statuses",
"active": true,
"events": ["job.status, order.status"],
"createdAt": "2022-02-17T08:47:11.377149Z",
"updatedAt": "2022-02-17T08:47:11.377149Z",
"secret": "QWZTFnMEXhqZKNmu"
},
"error": null
}
Parameter | Overview |
---|---|
data.id | string The webhook ID. |
data.url | string The URL of the webhook. |
data.name | string The name of the webhook. |
data.active | boolean Whether this webhook is active. |
data.events | array of strings A list of events that trigger the webhook. |
data.createdAt | string The timestamp when the webhook was created. |
data.updatedAt | string The timestamp when the webhook was last updated. |
data.secret | string The secret used to generate webhook signatures. |
Test a created webhook
To test a created webhook, call the /workspaces/{workspace-id}/webhooks/{webhook-id}/tests endpoint with your workspace ID and the created webhook ID as path parameters.
Request
POST /workspaces/{workspace-id}/webhooks/{webhook-id}/tests HTTP/1.1
Host: api.up42.com
Content-Type: application/json
Authorization: Bearer {token}
Parameter | Overview |
---|---|
eventNames | array of strings Specify if you need to test a specific event type for this webhook. If empty, the endpoint will run tests for all subscribed events. |
See request example
{
"eventNames": ["job.status"]
}
Response
See response example
{
"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
}
],
"startedAt": "2021-12-21T10:14:27Z",
"finishedAt": null
}
}
},
"response": "HttpResponse[https://my.sample.endpoint.com/, 200 OK]"
}
]
},
"error": null
}
Parameter | Overview |
---|---|
data.testsRun | integer Total number of test requests executed. |
data.testsSucceeded | integer Number of successful test requests. |
data.testsFailed | integer Number of failed test requests. |