{ "swagger": "2.0", "info": { "version": "2.2.12", "title": "Subscriptions", "description": "Subscriptions Module API Specification" }, "host": "admin.alertsense.com", "basePath": "/api", "schemes": [ "http", "https" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "paths": { "/v2/settings/subscriptions": { "get": { "description": "Gets a paged list of `Subscription` objects.", "operationId": "getSubscriptions", "parameters": [ { "$ref": "#/parameters/page" }, { "$ref": "#/parameters/pageSize" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/pagedSubscriptionResponse" }, "examples": { "application/json": { "totalItemCount": 2, "pageCount": 1, "page": 1, "pageSize": 25, "items": [ { "id": "00f80df7-9e79-49ea-9e02-e265ea33ae40", "uri": "https://dev.alertsense.com/hooks", "secret": "Zw2'1*pDg8X(Sj)76Mr_Yn.5f3T-!z4A", "security": { "apiKey": "my-super-fancy-key", "type": "apiKey" }, "eventTypes": [ { "name": "alert.sent", "description": "An alert was sent." }, { "name": "namedIncident.created", "description": "A named incident was created." } ], "isActive": true, "createdOn": "2016-12-09T13:06:08.260+0000", "modifiedOn": "2016-12-10T10:27:31.260+0000" }, { "id": "1072a38d-b856-495b-8f78-48b08a143889", "uri": "https://dev.alertsense.com/other-hooks", "secret": "sX_73yP.W4'joS1-F5!q)m2KZ8*k0iT~", "security": null, "eventTypes": [ { "name": "alert.sent", "description": "An alert was sent." } ], "isActive": true, "createdOn": "2016-11-14T19:06:08.260+0000", "modifiedOn": "2016-12-03T16:27:31.260+0000" } ], "hasErrors": false, "isValid": true } } } }, "tags": [ "subscriptions" ] }, "post": { "description": "Create a new `Subscription` object.", "operationId": "createSubscription", "parameters": [ { "in": "body", "name": "createSubscriptionRequest", "required": true, "schema": { "$ref": "#/definitions/createSubscriptionRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/singleSubscriptionResponse" }, "examples": { "application/json": { "id": "00f80df7-9e79-49ea-9e02-e265ea33ae40", "uri": "https://dev.alertsense.com/hooks", "secret": "Zw2'1*pDg8X(Sj)76Mr_Yn.5f3T-!z4A", "security": { "username": "john.q.user", "type": "basic" }, "eventTypes": [ { "name": "alert.sent", "description": "An alert was sent." }, { "name": "namedIncident.created", "description": "A named incident was created." } ], "isActive": true, "createdOn": "2016-12-09T13:06:08.260+0000", "modifiedOn": "2016-12-10T10:27:31.260+0000" } } }, "403": { "description": "Forbidden.", "schema": { "$ref": "#/definitions/errorResponse" } } }, "tags": [ "subscriptions" ] } }, "/v2/settings/subscriptions/{id}": { "get": { "description": "Gets a single `Subscription` object.", "operationId": "getSubscription", "parameters": [ { "in": "path", "name": "id", "description": "", "required": true, "format": "guid", "type": "string" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/singleSubscriptionResponse" }, "examples": { "application/json": { "item": [ { "id": "00f80df7-9e79-49ea-9e02-e265ea33ae40", "uri": "https://dev.alertsense.com/hooks", "secret": "Zw2'1*pDg8X(Sj)76Mr_Yn.5f3T-!z4A", "security": { "headers": { "X-Client-Id": "my-client-id", "X-Client-Token": "my-client-token" }, "type": "header" }, "eventTypes": [ { "name": "alert.sent", "description": "An alert was sent." }, { "name": "namedIncident.created", "description": "A named incident was created." } ], "isActive": true, "createdOn": "2016-12-09T13:06:08.260+0000", "modifiedOn": "2016-12-10T10:27:31.260+0000" } ], "hasErrors": false, "isValid": true } } } }, "tags": [ "subscriptions" ] }, "put": { "description": "Update an existing `Subscription` object.", "operationId": "updateSubscription", "parameters": [ { "in": "path", "name": "id", "description": "", "required": true, "format": "guid", "type": "string" }, { "in": "body", "name": "updateSubscriptionRequest", "required": true, "schema": { "$ref": "#/definitions/updateSubscriptionRequest" } } ], "responses": { "204": { "description": "Success" }, "403": { "description": "Forbidden.", "schema": { "$ref": "#/definitions/errorResponse" } } }, "tags": [ "subscriptions" ] }, "delete": { "description": "Delete an existing `Subscription` object.", "operationId": "deleteSubscription", "parameters": [ { "in": "path", "name": "id", "description": "", "required": true, "format": "guid", "type": "string" } ], "responses": { "204": { "description": "Success" }, "403": { "description": "Forbidden.", "schema": { "$ref": "#/definitions/errorResponse" } } }, "tags": [ "subscriptions" ] } }, "/v2/settings/subscriptions/{id}/history": { "get": { "description": "Gets a paged list of `SubscriptionHistory` objects. Subscription history is available for the previous 30 days.", "operationId": "getSubscriptionHistory", "parameters": [ { "in": "path", "name": "id", "description": "The Id of the Subscription for which to get the history.", "required": true, "format": "guid", "type": "string" }, { "in": "query", "name": "eventIds", "description": "Filter by specific event Ids.", "required": false, "type": "array", "items": { "type": "string", "format": "guid" } }, { "in": "query", "name": "eventTypes", "description": "Filter by specific event types.", "required": false, "type": "array", "items": { "type": "string" } }, { "in": "query", "name": "startDateTime", "description": "Filter by history items newer than the specified datetime.", "required": false, "type": "string", "format": "date-time" }, { "in": "query", "name": "endDateTime", "description": "Filter by history items older than the specified datetime.", "required": false, "type": "string", "format": "date-time" }, { "$ref": "#/parameters/page" }, { "$ref": "#/parameters/pageSize" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/pagedSubscriptionHistoryResponse" }, "examples": { "application/json": { "totalItemCount": 2, "pageCount": 1, "page": 1, "pageSize": 25, "items": [ { "subscriptionId": "f373c398970b43b08c20c977fbe8cbfb", "eventId": "f6f21cf4e6ee454aaa895e90bd174b67", "eventType": "tasklist.deleted", "request": { "resource": "/", "headers": { "Accept": "application/json, application/xml, text/json, text/x-json, text/javascript, text/xml" }, "body": "{\"id\":\"f6f21cf4e6ee454aaa895e90bd174b67\",\"timestamp\":\"2017-05-12T16:47:32.0780000-05:00\",\"eventType\":\"tasklist.deleted\",\"data\":{\"id\":\"5946638fa37a4b6285f897682adb8655\",\"title\":\"No Task ExternalIds\",\"description\":\"This tasklist has no ExternalIds set on the tasks.\",\"createdOn\":\"2017-05-12T16:47:10.9700000-05:00\",\"modifiedOn\":\"2017-05-12T16:47:10.9700000-05:00\",\"owner\":{\"id\":1005,\"externalId\":\"external1005\",\"name\":{\"familyName\":\"McLargeHuge\",\"givenName\":\"Big\"}},\"owners\":[{\"id\":1005,\"externalId\":\"external1005\",\"name\":{\"familyName\":\"McLargeHuge\",\"givenName\":\"Big\"}}],\"ownerLabel\":\"Big McLargeHuge\",\"assignees\":[{\"id\":1007,\"externalId\":\"external1007\",\"name\":{\"familyName\":\"Butterworth\",\"givenName\":\"Bertha\"}},{\"id\":1008,\"externalId\":\"external1008\",\"name\":{\"familyName\":\"Locust\",\"givenName\":\"Babe\"}}],\"assigneeLabel\":\"Bertha Butterworth, Babe Locust\",\"priority\":\"Emergency\",\"isActive\":true,\"isComplete\":false,\"totalTasks\":4,\"completedTasks\":0,\"tasks\":[{\"id\":\"9e9b9f6de66c40a399527af09167dd5d\",\"sequence\":1,\"title\":\"Task 1\",\"description\":\"Description for Task 1\",\"isComplete\":false,\"isSkipped\":false,\"activities\":[]},{\"id\":\"1cb73b2179ae4554b428f0d1c340ef99\",\"sequence\":2,\"title\":\"Task 2\",\"description\":\"Description for Task 2\",\"isComplete\":false,\"isSkipped\":false,\"activities\":[]},{\"id\":\"ccf83b9a0a584cb6a0ab1924603d9995\",\"sequence\":3,\"title\":\"Task 3\",\"description\":\"Description for Task 3\",\"isComplete\":false,\"isSkipped\":false,\"activities\":[]},{\"id\":\"6cde3cbf5c4c4ce8b7998ac1c529ab1a\",\"sequence\":4,\"title\":\"Task 4\",\"description\":\"Description for Task 4\",\"isComplete\":false,\"isSkipped\":false,\"activities\":[]}]}}", "method": "POST", "uri": "http://localhost:8765/" }, "attempt": 1, "responseCode": 200, "response": { "statusCode": 200, "statusDescription": "OK", "content": "", "headers": { "Vary": "Accept", "Content-Length": "0", "Content-Type": "application/json; charset=utf-8", "Date": "Fri, 12 May 2017 16:47:32 GMT", "Server": "Microsoft-HTTPAPI/2.0", "X-Powered-By": "ServiceStack/4.54 Win32NT/.NET" }, "responseUri": "http://localhost:8765/" }, "duration": 3, "timestamp": "/Date(1494607652117+0000)/" }, { "subscriptionId": "f373c398970b43b08c20c977fbe8cbfb", "eventId": "6bb566886ff842c4a7cb4ce2c6cfee21", "eventType": "tasklist.created", "request": { "resource": "/", "headers": { "Accept": "application/json, application/xml, text/json, text/x-json, text/javascript, text/xml" }, "body": "{\"id\":\"6bb566886ff842c4a7cb4ce2c6cfee21\",\"timestamp\":\"2017-05-12T16:47:11.1560000-05:00\",\"eventType\":\"tasklist.created\",\"data\":{\"id\":\"5946638fa37a4b6285f897682adb8655\",\"title\":\"No Task ExternalIds\",\"description\":\"This tasklist has no ExternalIds set on the tasks.\",\"createdOn\":\"2017-05-12T16:47:10.9700000-05:00\",\"modifiedOn\":\"2017-05-12T16:47:10.9700000-05:00\",\"owner\":{\"id\":1005,\"externalId\":\"external1005\",\"name\":{\"familyName\":\"McLargeHuge\",\"givenName\":\"Big\"}},\"owners\":[{\"id\":1005,\"externalId\":\"external1005\",\"name\":{\"familyName\":\"McLargeHuge\",\"givenName\":\"Big\"}}],\"ownerLabel\":\"Big McLargeHuge\",\"assignees\":[{\"id\":1007,\"externalId\":\"external1007\",\"name\":{\"familyName\":\"Butterworth\",\"givenName\":\"Bertha\"}},{\"id\":1008,\"externalId\":\"external1008\",\"name\":{\"familyName\":\"Locust\",\"givenName\":\"Babe\"}}],\"assigneeLabel\":\"Bertha Butterworth, Babe Locust\",\"priority\":\"Emergency\",\"isActive\":true,\"isComplete\":false,\"totalTasks\":4,\"completedTasks\":0,\"tasks\":[{\"id\":\"9e9b9f6de66c40a399527af09167dd5d\",\"sequence\":1,\"title\":\"Task 1\",\"description\":\"Description for Task 1\",\"isComplete\":false,\"isSkipped\":false,\"activities\":[]},{\"id\":\"1cb73b2179ae4554b428f0d1c340ef99\",\"sequence\":2,\"title\":\"Task 2\",\"description\":\"Description for Task 2\",\"isComplete\":false,\"isSkipped\":false,\"activities\":[]},{\"id\":\"ccf83b9a0a584cb6a0ab1924603d9995\",\"sequence\":3,\"title\":\"Task 3\",\"description\":\"Description for Task 3\",\"isComplete\":false,\"isSkipped\":false,\"activities\":[]},{\"id\":\"6cde3cbf5c4c4ce8b7998ac1c529ab1a\",\"sequence\":4,\"title\":\"Task 4\",\"description\":\"Description for Task 4\",\"isComplete\":false,\"isSkipped\":false,\"activities\":[]}]}}", "method": "POST", "uri": "http://localhost:8765/" }, "attempt": 1, "responseCode": 200, "response": { "statusCode": 200, "statusDescription": "OK", "content": "", "headers": { "Vary": "Accept", "Content-Length": "0", "Content-Type": "application/json; charset=utf-8", "Date": "Fri, 12 May 2017 16:47:11 GMT", "Server": "Microsoft-HTTPAPI/2.0", "X-Powered-By": "ServiceStack/4.54 Win32NT/.NET" }, "responseUri": "http://localhost:8765/" }, "duration": 54, "timestamp": "/Date(1494607632613+0000)/" } ], "hasErrors": false, "isValid": true } } } }, "tags": [ "subscriptions" ] } }, "/v2/settings/subscriptions/{id}/test": { "get": { "description": "Request a test hook be sent to the specified `Subscription`.", "operationId": "getSubscriptionTest", "parameters": [ { "in": "path", "name": "id", "description": "The Id of the Subscription to test.", "required": true, "format": "guid", "type": "string" } ], "responses": { "200": { "description": "Success" }, "401": { "description": "401 unauthorized" }, "404": { "description": "404 Not Found" }, "500": { "description": "500 response" } }, "tags": [ "subscriptions" ] } }, "/v2/settings/subscriptions/eventTypes": { "get": { "description": "Gets a paged list of `EventType` objects.", "operationId": "getEventTypes", "parameters": [ { "$ref": "#/parameters/page" }, { "$ref": "#/parameters/pageSize" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/pagedEventTypesResponse" }, "examples": { "application/json": { "totalItemCount": 2, "pageCount": 1, "page": 1, "pageSize": 25, "items": [ { "name": "alert.sent", "description": "An alert was sent." }, { "name": "namedIncident.created", "description": "A named incident was created." } ], "hasErrors": false, "isValid": true } } } }, "tags": [ "subscriptions" ] } } }, "parameters": { "page": { "name": "page", "in": "query", "description": "The page number of items to return. (1 by default)", "required": false, "default": 1, "type": "integer", "format": "int32" }, "pageSize": { "name": "pageSize", "in": "query", "description": "The desired number of items per page. (25 by default)", "default": 25, "required": false, "type": "integer", "format": "int32" }, "search": { "name": "search", "in": "query", "description": "A value matched against one or more resource properties.", "required": false, "type": "string" }, "sort": { "name": "sort", "in": "query", "description": "A comma seperated list of properties to order by. Properties preceded by a '-' will be ordered descending. (e.g. ?sort=lastName,firstName,-responseTime). Property names are case insensitive.", "required": false, "type": "string" }, "level": { "name": "level", "in": "query", "description": "The level of history items.", "required": false, "type": "string", "enum": [ "Debug", "Information", "Warning", "Error" ] }, "integrationsCategory": { "name": "category", "in": "query", "description": "The category of integration history items.", "required": false, "type": "string", "enum": [ "None", "Event", "Trigger", "Action", "Status" ] }, "startDate": { "name": "startDate", "in": "query", "description": "The starting date for the date range.", "required": false, "type": "string", "format": "date-time" }, "endDate": { "name": "endDate", "in": "query", "description": "The ending date for the date range.", "required": false, "type": "string", "format": "date-time" } }, "responses": { "204": { "description": "Success. No Content." }, "400": { "description": "Bad request.", "schema": { "$ref": "#/definitions/errorResponse" }, "examples": { "application/json": { "error": "Bad request." } } }, "401": { "description": "Unauthorized.", "schema": { "$ref": "#/definitions/errorResponse" }, "examples": { "application/json": { "error": "Unauthorized." } } }, "403": { "description": "Forbidden.", "schema": { "$ref": "#/definitions/errorResponse" }, "examples": { "application/json": { "error": "Forbidden." } } }, "404": { "description": "Not Found.", "schema": { "$ref": "#/definitions/errorResponse" }, "examples": { "application/json": { "error": "Not Found." } } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/errorResponse" }, "examples": { "application/json": { "error": "Unexpected server error." } } } }, "definitions": { "apiResponse": { "discriminator": "type", "properties": { "status": { "$ref": "#/definitions/responseStatus" }, "hasErrors": { "description": "Set true when status.isSuccess is false.", "type": "boolean" }, "isValid": { "description": "Set false on API parameter validation failures.", "type": "boolean" } }, "type": "object" }, "createSubscriptionRequest": { "properties": { "uri": { "description": "The URI of the resource to send the web hook to", "format": "url", "type": "string" }, "secret": { "description": "The secret key that will be used when generating the request signature. If left blank, requests will not be signed.", "type": "string" }, "security": { "$ref": "#/definitions/subscriptionSecurity" }, "eventTypes": { "description": "The list of eventType Ids to include in this subscription.", "items": { "type": "string" }, "type": "array" }, "isActive": { "description": "Whether the subscription is currently active or not", "type": "boolean" } }, "type": "object" }, "errorResponse": { "properties": { "error": { "type": "string" } }, "type": "object" }, "eventType": { "description": "A type of event that can be subscribed to.", "properties": { "name": { "type": "string" }, "description": { "type": "string" } }, "type": "object" }, "pagedApiResponse": { "discriminator": "type", "properties": { "page": { "format": "int32", "type": "integer" }, "pageCount": { "format": "int32", "type": "integer" }, "pageSize": { "format": "int32", "type": "integer" }, "totalItemCount": { "format": "int32", "type": "integer" }, "status": { "$ref": "#/definitions/responseStatus" }, "hasErrors": { "description": "Set true when status.isSuccess is false.", "type": "boolean" }, "isValid": { "description": "Set false on API parameter validation failures.", "type": "boolean" } }, "type": "object" }, "pagedEventTypesResponse": { "allOf": [ { "$ref": "#/definitions/pagedApiResponse" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/eventType" } } } } ], "type": "object" }, "pagedSubscriptionHistoryResponse": { "allOf": [ { "$ref": "#/definitions/pagedApiResponse" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/subscriptionHistory" } } } } ], "type": "object" }, "pagedSubscriptionResponse": { "allOf": [ { "$ref": "#/definitions/pagedApiResponse" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/subscription" } } } } ], "type": "object" }, "responseMessage": { "type": "object", "properties": { "severity": { "type": "string" }, "message": { "type": "string" }, "resourceKey": { "type": "string" } }, "example": { "severity": "Warning", "message": "My custom message", "resourceKey": "warnings.customMessage" } }, "responseStatus": { "type": "object", "properties": { "resourceKey": { "type": "string" }, "isSuccess": { "description": "False when errorCode is not None or there is an errorMessage or validationFailures.", "type": "boolean" }, "errorCode": { "type": "string" }, "errorMessage": { "type": "string" }, "validationFailures": { "description": "API parameter validation failures.", "type": "array", "items": { "$ref": "#/definitions/validationFailure" } }, "messages": { "type": "array", "items": { "$ref": "#/definitions/responseMessage" } } }, "example": { "resourceKey": "error.notFound", "isSuccess": false, "errorCode": "NotFound", "errorMessage": "The item cannot be found.", "validationFailures": [ { "propertyName": "email", "errorMessage": "Value is required", "errorCode": "Required", "attemptedValue": "chester.tester@mailinator.com" } ], "messages": [ { "severity": "Warning", "message": "My custom message" } ] } }, "singleSubscriptionResponse": { "allOf": [ { "$ref": "#/definitions/apiResponse" }, { "properties": { "item": { "$ref": "#/definitions/subscription" } } } ], "type": "object" }, "subscription": { "description": "A subscription to a web hook event.", "properties": { "id": { "description": "The Id of the subscription", "format": "guid", "type": "string" }, "uri": { "description": "The URI of the resource to send the web hook to", "format": "url", "type": "string" }, "secret": { "description": "The secret key that will be used when generating the request signature", "type": "string" }, "security": { "$ref": "#/definitions/subscriptionSecurity" }, "eventTypes": { "items": { "$ref": "#/definitions/eventType" }, "type": "array" }, "isActive": { "description": "Whether the subscription is currently active or not", "type": "boolean" }, "createdOn": { "description": "The datetime the subscription was created", "format": "date-time", "type": "string" }, "modifiedOn": { "description": "The datetime the subscription was last modified", "format": "date-time", "type": "string" } }, "type": "object" }, "subscriptionHistory": { "properties": { "subscriptionId": { "description": "The Id of the subscription.", "format": "guid", "type": "string" }, "eventId": { "description": "The Id of the event.", "format": "guid", "type": "string" }, "eventType": { "description": "The name of the event type.", "type": "string" }, "request": { "properties": { "resource": { "description": "The resource requested at the remote server.", "type": "string" }, "headers": { "description": "A dictionary of the header / value pairs sent with the request.", "type": "object" }, "body": { "description": "The string representation of the body of the request.", "type": "string" }, "method": { "description": "The HTTP method used with the request (GET, POST, etc).", "type": "string" }, "uri": { "description": "The URI requested.", "type": "string" } }, "type": "object" }, "attempt": { "description": "The attempt number when sending the web hook for this SubscriptionId and EventId.", "type": "integer" }, "responseCode": { "description": "The HTTP status code returned by the remote server. If a response is not received, this value will be 0.", "type": "integer" }, "response": { "properties": { "statusCode": { "description": "The HTTP status code returned by the remote server. If a response is not received, this value will be 0.", "type": "integer" }, "statusDescription": { "description": "The description of the status code returned by the remote server.", "type": "string" }, "content": { "description": "The string representation of the body of the response.", "type": "string" }, "headers": { "description": "A dictionary of the header / value pairs returned in the response.", "type": "object" }, "responseUri": { "description": "The URI that responded to the request.", "type": "string" } }, "type": "object" }, "duration": { "description": "The duration of the request in milliseconds", "type": "integer" }, "timestamp": { "description": "The time at which the request was made.", "type": "string", "format": "date-time" } }, "type": "object" }, "subscriptionSecurity": { "discriminator": "discriminator", "properties": { "type": { "enum": [ "none", "apiKey", "basic", "header", "oauth" ], "type": "string" } }, "type": "object" }, "updateSubscriptionRequest": { "properties": { "id": { "description": "The Id of the web hook to update", "format": "guid", "type": "string" }, "uri": { "description": "The URI of the resource to send the web hook to", "format": "url", "type": "string" }, "secret": { "description": "The secret key that will be used when generating the request signature. If left blank, requests will not be signed.", "type": "string" }, "security": { "$ref": "#/definitions/subscriptionSecurity" }, "eventTypes": { "items": { "type": "string" }, "type": "array" }, "isActive": { "description": "Whether the subscription is currently active or not", "type": "boolean" } }, "type": "object" }, "validationFailure": { "type": "object", "properties": { "propertyName": { "type": "string" }, "errorMessage": { "type": "string" }, "errorCode": { "type": "string" }, "attemptedValue": { "type": "object" }, "resourceKey": { "type": "string" } }, "example": { "propertyName": "email", "errorMessage": "Value is required", "errorCode": "Required", "attemptedValue": "chester.tester@mailinator.com", "resourceKey": "validation.required" } } } }