Create webhooks

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: `job.status` — Every time a job changes its status. `order.status` — When a new order has been completed, successfully or not.
`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
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
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.