Webhooks

Download schema

Endpoints for the team's webhook endpoints and the events and deliveries sent to them. Webhooks send a signed request to an endpoint when something happens in the team, see the webhooks guide for verifying them.

List webhook endpoints

GET

https://server.chief.app/api/v1

/webhooks/endpoints

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

List the team's webhook endpoints, oldest first. Signing secrets are not included.

List webhook endpoints › query Parameters

per_page

integer · min: 1 · max: 100

Number of results per page.

Default: 50

page

integer · min: 1

Page number to return.

Default: 1

List webhook endpoints › Responses

Paginated set of WebhookEndpoint

WebhookEndpoint[] · required

object · required

GET/webhooks/endpoints

curl https://server.chief.app/api/v1/webhooks/endpoints \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "webhook_01m6v2nkcfd8n7hg5r9t5k0ys6",
      "url": "https://example.com/webhooks/chief",
      "description": "Paging",
      "events": [
        "server.offline",
        "server.online"
      ],
      "status": "enabled",
      "disabled_reason": "manual",
      "disabled_at": "disabled_at",
      "failing_since": "failing_since",
      "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw",
      "previous_secret_expires_at": "previous_secret_expires_at",
      "created_at": "created_at",
      "updated_at": "updated_at"
    }
  ],
  "links": {
    "first": "first",
    "last": "last",
    "prev": "prev",
    "next": "next"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": "url",
        "label": "label",
        "active": true
      }
    ],
    "path": "path",
    "per_page": 0,
    "to": 1,
    "total": 0
  }
}

json

application/json

Create a webhook endpoint

POST

https://server.chief.app/api/v1

/webhooks/endpoints

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Add an endpoint that receives the chosen events. The response is the only time its signing secret is returned until it is rotated. Fails with 422 when the team's plan has no room for another endpoint.

Create a webhook endpoint › Request Body

CreateWebhookEndpointRequest

url

string · uri · maxLength: 2048 · required

HTTPS URL that receives the events, it must resolve to a public address.

Example: https://example.com/webhooks/chief

events

string[] · minItems: 1 · unique · required

Event types the endpoint receives, * for every event including types added later.

Enum values:

server.created

server.enrolled

server.updated

server.deleted

server.offline

server.online

server.reboot_stalled

Example: ["server.offline","server.online"]

description

string | null · maxLength: 255

What the endpoint is for, shown in the dashboard.

Example: Paging

Create a webhook endpoint › Responses

WebhookEndpoint

WebhookEndpoint · required

POST/webhooks/endpoints

curl https://server.chief.app/api/v1/webhooks/endpoints \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "url": "https://example.com/webhooks/chief",
  "description": "Paging",
  "events": [
    "server.offline",
    "server.online"
  ]
}'

Example Request Body

{
  "url": "https://example.com/webhooks/chief",
  "description": "Paging",
  "events": [
    "server.offline",
    "server.online"
  ]
}

json

Example Responses

{
  "data": {
    "id": "webhook_01m6v2nkcfd8n7hg5r9t5k0ys6",
    "url": "https://example.com/webhooks/chief",
    "description": "Paging",
    "events": [
      "server.offline",
      "server.online"
    ],
    "status": "enabled",
    "disabled_reason": "manual",
    "disabled_at": "disabled_at",
    "failing_since": "failing_since",
    "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw",
    "previous_secret_expires_at": "previous_secret_expires_at",
    "created_at": "created_at",
    "updated_at": "updated_at"
  }
}

json

application/json

List webhook event types

GET

https://server.chief.app/api/v1

/webhooks/event-types

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

List the event types endpoints can subscribe to, with the heading they are grouped under and when they are sent.

List webhook event types › Responses

Array of WebhookEventTypeDetails

WebhookEventTypeDetails[] · required

Get a webhook endpoint

GET

https://server.chief.app/api/v1

/webhooks/endpoints/{endpoint}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Get an endpoint of the team. Its signing secret is not included.

Get a webhook endpoint › path Parameters

endpoint

string · required

Get a webhook endpoint › Responses

WebhookEndpoint

WebhookEndpoint · required

Update a webhook endpoint

PATCH

https://server.chief.app/api/v1

/webhooks/endpoints/{endpoint}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Change an endpoint's URL, description or events. Fields left out keep their value.

Update a webhook endpoint › path Parameters

endpoint

string · required

Update a webhook endpoint › Request Body

UpdateWebhookEndpointRequest

url

string · uri · maxLength: 2048

HTTPS URL that receives the events, it must resolve to a public address.

Example: https://example.com/webhooks/chief

description

string | null · maxLength: 255

What the endpoint is for, shown in the dashboard. Null removes it.

Example: Paging

events

string[] · minItems: 1 · unique

Event types the endpoint receives, * for every event including types added later. Replaces the current list.

Enum values:

server.created

server.enrolled

server.updated

server.deleted

server.offline

server.online

server.reboot_stalled

Example: ["*"]

Update a webhook endpoint › Responses

WebhookEndpoint

WebhookEndpoint · required

PATCH/webhooks/endpoints/{endpoint}

curl https://server.chief.app/api/v1/webhooks/endpoints/:endpoint \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "url": "https://example.com/webhooks/chief",
  "description": "Paging",
  "events": [
    "*"
  ]
}'

Example Request Body

{
  "url": "https://example.com/webhooks/chief",
  "description": "Paging",
  "events": [
    "*"
  ]
}

json

Example Responses

{
  "data": {
    "id": "webhook_01m6v2nkcfd8n7hg5r9t5k0ys6",
    "url": "https://example.com/webhooks/chief",
    "description": "Paging",
    "events": [
      "server.offline",
      "server.online"
    ],
    "status": "enabled",
    "disabled_reason": "manual",
    "disabled_at": "disabled_at",
    "failing_since": "failing_since",
    "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw",
    "previous_secret_expires_at": "previous_secret_expires_at",
    "created_at": "created_at",
    "updated_at": "updated_at"
  }
}

json

application/json

Delete a webhook endpoint

DELETE

https://server.chief.app/api/v1

/webhooks/endpoints/{endpoint}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Delete an endpoint with its delivery log. Deliveries still waiting for an attempt are not sent.

Delete a webhook endpoint › path Parameters

endpoint

string · required

Delete a webhook endpoint › Responses

No content

No data returned

Enable a webhook endpoint

POST

https://server.chief.app/api/v1

/webhooks/endpoints/{endpoint}/enable

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Start sending events to a disabled endpoint again. Events that happened while it was disabled are not sent, resend them from its deliveries or the events.

Enable a webhook endpoint › path Parameters

endpoint

string · required

Enable a webhook endpoint › Responses

WebhookEndpoint

WebhookEndpoint · required

Disable a webhook endpoint

POST

https://server.chief.app/api/v1

/webhooks/endpoints/{endpoint}/disable

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Stop sending events to an endpoint. Its deliveries waiting for a retry are cancelled.

Disable a webhook endpoint › path Parameters

endpoint

string · required

Disable a webhook endpoint › Responses

WebhookEndpoint

WebhookEndpoint · required

Rotate a webhook endpoint's secret

POST

https://server.chief.app/api/v1

/webhooks/endpoints/{endpoint}/rotate-secret

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Replace the signing secret and return the new one. For the next 24 hours deliveries are signed with both, so receivers can switch without rejecting any. Fails with 422 while the secret from the last rotation still signs, unless replace_previous is true.

Rotate a webhook endpoint's secret › path Parameters

endpoint

string · required

Rotate a webhook endpoint's secret › Request Body

RotateWebhookSecretRequest

replace_previous

boolean

Rotate even though the secret from the last rotation still signs deliveries. That secret stops signing right away, receivers that only know it start rejecting deliveries.

Default: false

Rotate a webhook endpoint's secret › Responses

WebhookEndpoint

WebhookEndpoint · required

POST/webhooks/endpoints/{endpoint}/rotate-secret

curl https://server.chief.app/api/v1/webhooks/endpoints/:endpoint/rotate-secret \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "replace_previous": false
}'

Example Request Body

{
  "replace_previous": false
}

json

Example Responses

{
  "data": {
    "id": "webhook_01m6v2nkcfd8n7hg5r9t5k0ys6",
    "url": "https://example.com/webhooks/chief",
    "description": "Paging",
    "events": [
      "server.offline",
      "server.online"
    ],
    "status": "enabled",
    "disabled_reason": "manual",
    "disabled_at": "disabled_at",
    "failing_since": "failing_since",
    "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw",
    "previous_secret_expires_at": "previous_secret_expires_at",
    "created_at": "created_at",
    "updated_at": "updated_at"
  }
}

json

application/json

Send a test event

POST

https://server.chief.app/api/v1

/webhooks/endpoints/{endpoint}/test

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Send a webhook_endpoint.test event to an enabled endpoint, to check that it receives and verifies deliveries. The delivery is queued, get it later to see how it went.

Send a test event › path Parameters

endpoint

string · required

Send a test event › Responses

WebhookDelivery

WebhookDelivery · required

POST/webhooks/endpoints/{endpoint}/test

curl https://server.chief.app/api/v1/webhooks/endpoints/:endpoint/test \
  --request POST \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "id": "delivery_01m6v3f5b0c8z6w4k2t9r7p5n3",
    "endpoint_id": "webhook_01m6v2nkcfd8n7hg5r9t5k0ys6",
    "event_id": "event_01m6v3f5aydrktmzrbpz1pqh7e",
    "event_type": "server.created",
    "status": "pending",
    "attempts": 0,
    "next_attempt_at": "next_attempt_at",
    "last_attempted_at": "last_attempted_at",
    "last_response_status": 0,
    "created_at": "created_at",
    "attempt_log": [
      {
        "number": 0,
        "manual": true,
        "succeeded": true,
        "attempted_at": "attempted_at",
        "duration_ms": 0,
        "error": "timeout",
        "error_message": "error_message",
        "request": {
          "headers": {
            "key": "string"
          }
        },
        "response": {
          "status": 0,
          "headers": {
            "key": "string"
          },
          "body": "body",
          "truncated": true
        }
      }
    ]
  }
}

json

application/json

List an endpoint's deliveries

GET

https://server.chief.app/api/v1

/webhooks/endpoints/{endpoint}/deliveries

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

List the deliveries of events to an endpoint, newest first. Deliveries are kept for 30 days.

List an endpoint's deliveries › path Parameters

endpoint

string · required

List an endpoint's deliveries › query Parameters

per_page

integer · min: 1 · max: 100

Number of results per page.

Default: 50

page

integer · min: 1

Page number to return.

Default: 1

type

string · enum

Only events of this type.

Enum values:

server.created

server.enrolled

server.updated

server.deleted

server.offline

server.online

server.reboot_stalled

alert.fired

status

string · enum

Only deliveries in this state.

Enum values:

pending

succeeded

failed

cancelled

List an endpoint's deliveries › Responses

Paginated set of WebhookDelivery

WebhookDelivery[] · required

object · required

GET/webhooks/endpoints/{endpoint}/deliveries

curl https://server.chief.app/api/v1/webhooks/endpoints/:endpoint/deliveries \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "delivery_01m6v3f5b0c8z6w4k2t9r7p5n3",
      "endpoint_id": "webhook_01m6v2nkcfd8n7hg5r9t5k0ys6",
      "event_id": "event_01m6v3f5aydrktmzrbpz1pqh7e",
      "event_type": "server.created",
      "status": "pending",
      "attempts": 0,
      "next_attempt_at": "next_attempt_at",
      "last_attempted_at": "last_attempted_at",
      "last_response_status": 0,
      "created_at": "created_at",
      "attempt_log": [
        {
          "number": 0,
          "manual": true,
          "succeeded": true,
          "attempted_at": "attempted_at",
          "duration_ms": 0,
          "error": "timeout",
          "error_message": "error_message",
          "request": {
            "headers": {
              "key": "string"
            }
          },
          "response": {
            "status": 0,
            "headers": {
              "key": "string"
            },
            "body": "body",
            "truncated": true
          }
        }
      ]
    }
  ],
  "links": {
    "first": "first",
    "last": "last",
    "prev": "prev",
    "next": "next"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": "url",
        "label": "label",
        "active": true
      }
    ],
    "path": "path",
    "per_page": 0,
    "to": 1,
    "total": 0
  }
}

json

application/json

Get a webhook delivery

GET

https://server.chief.app/api/v1

/webhooks/deliveries/{delivery}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Get a delivery with every attempt: the request headers that were sent and the response the endpoint gave.

Get a webhook delivery › path Parameters

delivery

string · required

Get a webhook delivery › Responses

WebhookDelivery

object · required

GET/webhooks/deliveries/{delivery}

curl https://server.chief.app/api/v1/webhooks/deliveries/:delivery \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "id": "delivery_01m6v3f5b0c8z6w4k2t9r7p5n3",
    "endpoint_id": "webhook_01m6v2nkcfd8n7hg5r9t5k0ys6",
    "event_id": "event_01m6v3f5aydrktmzrbpz1pqh7e",
    "event_type": "server.created",
    "status": "pending",
    "attempts": 0,
    "next_attempt_at": "next_attempt_at",
    "last_attempted_at": "last_attempted_at",
    "last_response_status": 0,
    "created_at": "created_at",
    "attempt_log": [
      {
        "number": 0,
        "manual": true,
        "succeeded": true,
        "attempted_at": "attempted_at",
        "duration_ms": 0,
        "error": "timeout",
        "error_message": "error_message",
        "request": {
          "headers": {
            "key": "string"
          }
        },
        "response": {
          "status": 0,
          "headers": {
            "key": "string"
          },
          "body": "body",
          "truncated": true
        }
      }
    ]
  }
}

json

application/json

Resend a webhook delivery

POST

https://server.chief.app/api/v1

/webhooks/deliveries/{delivery}/resend

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Send a delivery again, whatever its state, as its next attempt with the same event ID. A resend does not use up automatic retries. The endpoint must be enabled.

Resend a webhook delivery › path Parameters

delivery

string · required

Resend a webhook delivery › Responses

WebhookDelivery

WebhookDelivery · required

POST/webhooks/deliveries/{delivery}/resend

curl https://server.chief.app/api/v1/webhooks/deliveries/:delivery/resend \
  --request POST \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "id": "delivery_01m6v3f5b0c8z6w4k2t9r7p5n3",
    "endpoint_id": "webhook_01m6v2nkcfd8n7hg5r9t5k0ys6",
    "event_id": "event_01m6v3f5aydrktmzrbpz1pqh7e",
    "event_type": "server.created",
    "status": "pending",
    "attempts": 0,
    "next_attempt_at": "next_attempt_at",
    "last_attempted_at": "last_attempted_at",
    "last_response_status": 0,
    "created_at": "created_at",
    "attempt_log": [
      {
        "number": 0,
        "manual": true,
        "succeeded": true,
        "attempted_at": "attempted_at",
        "duration_ms": 0,
        "error": "timeout",
        "error_message": "error_message",
        "request": {
          "headers": {
            "key": "string"
          }
        },
        "response": {
          "status": 0,
          "headers": {
            "key": "string"
          },
          "body": "body",
          "truncated": true
        }
      }
    ]
  }
}

json

application/json

List webhook events

GET

https://server.chief.app/api/v1

/webhooks/events

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

List the events sent to the team's endpoints, newest first. Events are only kept when an endpoint received them, for 30 days.

List webhook events › query Parameters

per_page

integer · min: 1 · max: 100

Number of results per page.

Default: 50

page

integer · min: 1

Page number to return.

Default: 1

type

string · enum

Only events of this type.

Enum values:

server.created

server.enrolled

server.updated

server.deleted

server.offline

server.online

server.reboot_stalled

alert.fired

List webhook events › Responses

Paginated set of WebhookEvent

WebhookEvent[] · required

object · required

GET/webhooks/events

curl https://server.chief.app/api/v1/webhooks/events \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "event_01m6v3f5aydrktmzrbpz1pqh7e",
      "type": "server.created",
      "api_version": "v1",
      "created_at": "created_at",
      "payload": {
        "key": {}
      },
      "deliveries": [
        {
          "id": "delivery_01m6v3f5b0c8z6w4k2t9r7p5n3",
          "endpoint_id": "webhook_01m6v2nkcfd8n7hg5r9t5k0ys6",
          "event_id": "event_01m6v3f5aydrktmzrbpz1pqh7e",
          "event_type": "server.created",
          "status": "pending",
          "attempts": 0,
          "next_attempt_at": "next_attempt_at",
          "last_attempted_at": "last_attempted_at",
          "last_response_status": 0,
          "created_at": "created_at",
          "attempt_log": [
            {
              "number": 0,
              "manual": true,
              "succeeded": true,
              "attempted_at": "attempted_at",
              "duration_ms": 0,
              "error": "timeout",
              "error_message": "error_message",
              "request": {
                "headers": {
                  "key": "string"
                }
              },
              "response": {
                "status": 0,
                "headers": {
                  "key": "string"
                },
                "body": "body",
                "truncated": true
              }
            }
          ]
        }
      ]
    }
  ],
  "links": {
    "first": "first",
    "last": "last",
    "prev": "prev",
    "next": "next"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": "url",
        "label": "label",
        "active": true
      }
    ],
    "path": "path",
    "per_page": 0,
    "to": 1,
    "total": 0
  }
}

json

application/json

Get a webhook event

GET

https://server.chief.app/api/v1

/webhooks/events/{event}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Get an event with its payload and its delivery to each endpoint.

Get a webhook event › path Parameters

event

string · required

Get a webhook event › Responses

WebhookEvent

object · required

GET/webhooks/events/{event}

curl https://server.chief.app/api/v1/webhooks/events/:event \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "id": "event_01m6v3f5aydrktmzrbpz1pqh7e",
    "type": "server.created",
    "api_version": "v1",
    "created_at": "created_at",
    "payload": {
      "key": {}
    },
    "deliveries": [
      {
        "id": "delivery_01m6v3f5b0c8z6w4k2t9r7p5n3",
        "endpoint_id": "webhook_01m6v2nkcfd8n7hg5r9t5k0ys6",
        "event_id": "event_01m6v3f5aydrktmzrbpz1pqh7e",
        "event_type": "server.created",
        "status": "pending",
        "attempts": 0,
        "next_attempt_at": "next_attempt_at",
        "last_attempted_at": "last_attempted_at",
        "last_response_status": 0,
        "created_at": "created_at",
        "attempt_log": [
          {
            "number": 0,
            "manual": true,
            "succeeded": true,
            "attempted_at": "attempted_at",
            "duration_ms": 0,
            "error": "timeout",
            "error_message": "error_message",
            "request": {
              "headers": {
                "key": "string"
              }
            },
            "response": {
              "status": 0,
              "headers": {
                "key": "string"
              },
              "body": "body",
              "truncated": true
            }
          }
        ]
      }
    ]
  }
}

json

application/json

Resend a webhook event

POST

https://server.chief.app/api/v1

/webhooks/events/{event}/resend

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Send an event to one of the team's enabled endpoints, as the next attempt of its delivery there or as a new delivery when it has none. Use it to catch an endpoint up after it was disabled.

Resend a webhook event › path Parameters

event

string · required

Resend a webhook event › Request Body

ResendWebhookEventRequest

endpoint

string · required

ID of the endpoint to send the event to. It gets the event even when it did not receive it before, or does not subscribe to its type.

Example: webhook_01m6v2nkcfd8n7hg5r9t5k0ys6

Resend a webhook event › Responses

WebhookDelivery

WebhookDelivery · required

POST/webhooks/events/{event}/resend

curl https://server.chief.app/api/v1/webhooks/events/:event/resend \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "endpoint": "webhook_01m6v2nkcfd8n7hg5r9t5k0ys6"
}'

Example Request Body

{
  "endpoint": "webhook_01m6v2nkcfd8n7hg5r9t5k0ys6"
}

json

Example Responses

{
  "data": {
    "id": "delivery_01m6v3f5b0c8z6w4k2t9r7p5n3",
    "endpoint_id": "webhook_01m6v2nkcfd8n7hg5r9t5k0ys6",
    "event_id": "event_01m6v3f5aydrktmzrbpz1pqh7e",
    "event_type": "server.created",
    "status": "pending",
    "attempts": 0,
    "next_attempt_at": "next_attempt_at",
    "last_attempted_at": "last_attempted_at",
    "last_response_status": 0,
    "created_at": "created_at",
    "attempt_log": [
      {
        "number": 0,
        "manual": true,
        "succeeded": true,
        "attempted_at": "attempted_at",
        "duration_ms": 0,
        "error": "timeout",
        "error_message": "error_message",
        "request": {
          "headers": {
            "key": "string"
          }
        },
        "response": {
          "status": 0,
          "headers": {
            "key": "string"
          },
          "body": "body",
          "truncated": true
        }
      }
    ]
  }
}

json

application/json

Agent releases Webhook events