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

200 OK – Successfully updated the endpoint.
201 Created –
404 Not Found – Endpoint or relationship not found, or user unauthorized to perform action.
422 Unprocessable Entity – Invalid arguments.
4XX – Client error.
5XX – Server error.