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
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.
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.