Endpoints

The Endpoint resource

Endpoint is the destination for webhooks. It has URL, secret key and timeout/retry settings.

The main use-case of endpoint is configure it once on higher scope (e.g account/environments), and then re-use in many webhook configurations on a lower scopes (e.g. environments/workspaces).

Key path

Description

type* (string)

Available values: endpoints

id (string)

attributes.max-attempts (integer)

The number of retry attempts.

attributes.name* (string)

The name of the endpoint.

attributes.permissions (object)

attributes.secret-key (string)

The secret passphrase for HMAC signature.

attributes.timeout (integer)

The HTTP transaction timeout.

attributes.url* (string)

HTTP(s) destination URL.

relationships.account (object)

The account, this endpoint belongs to.

relationships.account.data.type* (string)

Available values: accounts

relationships.account.data.id* (string)

relationships.environment (object)

The environment, this endpoint belongs to.

relationships.environment.data.type* (string)

Available values: environments

relationships.environment.data.id* (string)

links.self (string)

List Endpoints

GET /api/iacp/v3/endpoints

This endpoint lists endpoints.

Query Parameters
  • filter[environment] (string) – The ID of the Environment

  • filter[account] (string) – The ID of the Account

  • page[number] (string) – Page number

  • page[size] (string) – Page size

  • sort (array) – The comma-separated list of attributes. (Available values: name, url)

  • query (string) – Query string

Example Request:

GET /api/iacp/v3/endpoints HTTP/1.1
Host: my.scalr.io
Prefer: profile=preview
Status Codes
  • 200 OK

    Success.

    Example Respone:

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    Preference-Applied: profile=preview
    
    {
      "data": [
        {
          "attributes": {
            "max-attempts": 3,
            "name": "anton",
            "permissions": {
              "webhook-endpoints:delete": true,
              "webhook-endpoints:update": true
            },
            "secret-key": "auphee1ieshaeQu8",
            "timeout": 15,
            "url": "https://hooks.example.com/services/3565654"
          },
          "id": "ep-t1jvkud6virv9fo",
          "links": {},
          "relationships": {
            "account": {
              "data": {
                "id": "acc-t2fcrq6h1v3nf0g",
                "type": "accounts"
              }
            },
            "environment": {
              "data": {
                "id": "env-sfuari395m7sck1",
                "type": "environments"
              }
            }
          },
          "type": "endpoints"
        },
        {"...": "..."}
      ],
      "included": null,
      "links": {
        "first": "https://my.scalr.io/api/iacp/v3/endpoints?page%5Bnumber%5D=1&page%5Bsize%5D=20",
        "last": "https://my.scalr.io/api/iacp/v3/endpoints?page%5Bnumber%5D=1&page%5Bsize%5D=20",
        "next": null,
        "prev": null,
        "self": "https://my.scalr.io/api/iacp/v3/endpoints?page%5Bnumber%5D=1&page%5Bsize%5D=20"
      },
      "meta": {
        "pagination": {
          "current-page": 1,
          "next-page": null,
          "prev-page": null,
          "total-count": 3,
          "total-pages": 1
        }
      }
    }
    

  • 404 Not Found – Account or environment not found or user unauthorized to perform action.

  • 4XX – Client error.

  • 5XX – Server error.

Create an Endpoint

POST /api/iacp/v3/endpoints

Create a new endpoint in the account or environment.

Request body:

Key path

Description

data.type* (string)

Available values: endpoints

data.id (string)

data.attributes.max-attempts (integer)

The number of retry attempts.

data.attributes.name* (string)

The name of the endpoint.

data.attributes.secret-key (string)

The secret passphrase for HMAC signature.

data.attributes.timeout (integer)

The HTTP transaction timeout.

data.attributes.url* (string)

HTTP(s) destination URL.

data.relationships.account (object)

The account, this endpoint belongs to.

data.relationships.account.data.type* (string)

Available values: accounts

data.relationships.account.data.id* (string)

data.relationships.environment (object)

The environment, this endpoint belongs to.

data.relationships.environment.data.type* (string)

Available values: environments

data.relationships.environment.data.id* (string)

Example Request:

POST /api/iacp/v3/endpoints HTTP/1.1
Host: my.scalr.io
Content-Type: application/vnd.api+json
Prefer: profile=preview

{
  "data": {
    "type": "endpoints",
    "attributes": {
      "name": "Example",
      "url": "https://hooks.example.com/services/6932045",
    },
    "relationships": {
      "account": {
        "data": {
          "type": "accounts",
          "id": "acc-t2fcrq6h1v3nf0g"
        }
      }
    }
  }
}
Status Codes
  • 201 Created

    The endpoint was created.

    Example Respone:

    HTTP/1.1 201 Created
    Content-Type: application/vnd.api+json
    Preference-Applied: profile=preview
    
    {
      "data": {
        "attributes": {
          "max-attempts": 3,
          "name": "Example",
          "permissions": {
            "webhook-endpoints:delete": true,
            "webhook-endpoints:update": true
          },
          "secret-key": "aoj4eiSaeyaroh?qu",
          "timeout": 3,
          "url": "https://hooks.example.com/services/6932045"
        },
        "id": "ep-t6tfr6tsfhvdqj0",
        "links": {
          "self": "https://my.scalr.io/api/iacp/v3/endpoints/ep-t6tfr6tsfhvdqj0"
        },
        "relationships": {
          "account": {
            "data": {
              "id": "acc-t2fcrq6h1v3nf0g",
              "type": "accounts"
            }
          },
          "environment": null
        },
        "type": "endpoints"
      },
      "included": null,
      "meta": null
    }
    

  • 404 Not Found – Account or environment relationship not found, or user unauthorized to perform action.

  • 422 Unprocessable Entity – Invalid arguments.

  • 4XX – Client error.

  • 5XX – Server error.

Delete an Endpoint

DELETE /api/iacp/v3/endpoints/{endpoint}
Parameters
  • endpoint (string) – The ID of the endpoint to delete.

Status Codes
  • 204 No Content – Successfully deleted the endpoint.

  • 404 Not Found – Endpoint not found, or user unauthorized to perform action.

  • 4XX – Client error.

  • 5XX – Server error.

Get an Endpoint

GET /api/iacp/v3/endpoints/{endpoint}

Show details of a specific endpoint.

Parameters
  • endpoint (string) – The ID of the endpoint.

Example Request:

GET /api/iacp/v3/endpoints/{endpoint} HTTP/1.1
Host: my.scalr.io
Prefer: profile=preview
Status Codes
  • 200 OK – Success.

  • 404 Not Found – Endpoint not found or user unauthorized to perform action.

  • 4XX – Client error.

  • 5XX – Server error.

Update Endpoint

PATCH /api/iacp/v3/endpoints/{endpoint}
Parameters
  • endpoint (string) – The ID of the endpoint to update.

Request body:

Key path

Description

data.type* (string)

Available values: endpoints

data.id (string)

data.attributes.max-attempts (integer)

The number of retry attempts.

data.attributes.name* (string)

The name of the endpoint.

data.attributes.secret-key (string)

The secret passphrase for HMAC signature.

data.attributes.timeout (integer)

The HTTP transaction timeout.

data.attributes.url* (string)

HTTP(s) destination URL.

data.relationships.account (object)

The account, this endpoint belongs to.

data.relationships.account.data.type* (string)

Available values: accounts

data.relationships.account.data.id* (string)

data.relationships.environment (object)

The environment, this endpoint belongs to.

data.relationships.environment.data.type* (string)

Available values: environments

data.relationships.environment.data.id* (string)

Example Request:

PATCH /api/iacp/v3/endpoints/{endpoint} HTTP/1.1
Host: my.scalr.io
Content-Type: application/vnd.api+json
Prefer: profile=preview

{
    "data": {
        "attributes": {
            "max-attempts": 1,
            "name": "string",
            "secret-key": "string",
            "timeout": 1,
            "url": "string"
        },
        "id": "string",
        "relationships": {
            "account": {
                "data": {
                    "id": "string",
                    "type": "accounts"
                }
            },
            "environment": {
                "data": {
                    "id": "string",
                    "type": "environments"
                }
            }
        },
        "type": "endpoints"
    }
}
Status Codes