Create webhooks

Create and test 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
}

ParameterOverview
data.namestring
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.titlestring
The title of the event.
data.categorystring
The type of events to notify about.
data.descriptionstring
The description of the event.
data.documentationstring
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}
ParameterOverview
eventsarray of strings / required
A list of events that trigger the webhook.
namestring / required
The name of the webhook.
urlstring / required
The URL of the webhook.
secretstring
The secret used to generate webhook signatures.
activeboolean
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
}

ParameterOverview
data.idstring
The webhook ID.
data.urlstring
The URL of the webhook.
data.namestring
The name of the webhook.
data.activeboolean
Whether this webhook is active.
data.eventsarray of strings
A list of events that trigger the webhook.
data.createdAtstring
The timestamp when the webhook was created.
data.updatedAtstring
The timestamp when the webhook was last updated.
data.secretstring
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}
ParameterOverview
eventNamesarray 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
}

ParameterOverview
data.testsRuninteger
Total number of test requests executed.
data.testsSucceededinteger
Number of successful test requests.
data.testsFailedinteger
Number of failed test requests.