# Subscribe
## OpenAPI Specification
```yaml
openapi: 3.0.1
info:
title: ''
description: ''
version: 1.0.0
paths:
/be/v1/subscriptions:
post:
summary: Subscribe
deprecated: false
description: >+
This endpoint can be used to subscribe your webservice or slack channel
to events emitted from the ROCKIT Edge. This is useful when you want
react to state changes on your apps automatically via a Webhook, e.g.
when the deployment of a DxF Image finished or an error occurred while
deploying the app. Or you want to be in the loop by the ROCKIT-Edge
sending you Slack messages.
On the ROCKIT Edge the following event types are present (where each
type has multiple different events):
1. **Import Request Task (`dltar`)**
* **submit**
The import request task has been submitted to the ROCKIT Edge processing pipeline.
* **begin**
The import request task has started.
* **end**
The import request has ended (successfully).
* **error**
The import request has failed.
* **exception**
The import request failed due to a wrong user input.
2. **Building ROCKIT Image failed (`mkraw`)**
* **submit**
The build task has been submitted to the processing pipeline.
* **begin**
The build task has started.
* **end**
The build task has ended (successfully).
* **error**
The build task has failed.
* **exception**
The build task failed due to a wrong user input.
3. **Publish Task (`deploy`)**
* **submit**
The publish task has been submitted to the ROCKIT Edge processing pipeline.
* **begin**
The publish task has ended successfully. The new ROCKIT image and patch files are available on the CDN origin(s). Old files will be removed in 24 hours.
* **end**
The publish task has ended (successfully).
* **error**
The publish task has failed. The associated app is still locked until the issue has been resoled.
A subscription associates one of the above mentioned events with a
receiver such as:
* A webhook which will be called by ROCKIT Edge.
* A Slack channel which ROCKIT Edge posts the event details.
## Webhook Specifications
The endpoint will be called with as a POST request with the following
headers and body schema:
**Destination URL**
When subscribing to an event as webhook please define the URL which will
be called by ROCKIT Edge such as
`https://www.acme.com/webhooks/import-build`
**Request Headers**
| Request Header | Descriptions |
| --- | --- |
| `Content-type` | `application/json` |
| `x-rockit-subscriptions` | JWT can be verified with the secret
obtained from `POST /be/v1/subscriptions`.|
The token validation in with NodeJS might look like:
```
const JWT = require ('jsonwebtoken')
let secretBase64 = 'bFJ6O0kuQGRyaEV0aD...'
let token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXV...'
try {
let decodedToken = JWT.verify (token, Buffer.from (secretBase64, "base64").toString ())
console.log ("valid token:", decodedToken)
} catch (e) {
console.error ("Invalid token")
console.error (e.stack)
}
```
## Slack
ROCKIT Edge events can also post notification messages to Slack. To
authenticate the access the Slack token of the Slack bot as well as the
target Slack channel identifier has to be specified.
## Register Subscriptions
The webhook which with the above described specifications or a Slack
channel can be registered by calling `/be/v1/subscriptions`. The content
of the message will carry the same payload as for the webhook in a more
human readable format.
### Required Permissions
`subscriptions.create`
See [Roles](https://edge.api.cloud.rockitplay.com/roles-3618377f0.md)
for more details.
tags:
- ROCKIT Edge - Backend API/Subscriptions
parameters:
- name: Authorization
in: header
description: >-
Use the access token obtained from [`POST
/be/v1/login`](https://edge.api.cloud.rockitplay.com/user-login-org-11611254e0.md)
or [`POST
/be/v1/refresh`](https://edge.api.cloud.rockitplay.com/refresh-11630082e0.md)
as Bearer token.
Mutually excluded with `x-rockit-api-key`.
required: true
example: Bearer {{_edge_org_admin_access_token}}
schema:
type: string
- name: x-rockit-tenant
in: header
description: >
Unique and immutable tenancy identifier obtained from the ROCKIT
Edge administrator.
Requires `x-rockit-username`,
`x-rockit-orgname` and `x-rockit-api-key`.
required: true
example: '{{EDGE_TENANT_NAME}}'
schema:
type: string
- name: x-rockit-orgname
in: header
description: >
Unique and immutable organization identifier obtained from the
ROCKIT Edge administrator.
Requires `x-rockit-tenant`,
`x-rockit-username` and `x-rockit-api-key`.
required: true
example: '{{EDGE_ORG_NAME}}'
schema:
type: string
- name: x-rockit-username
in: header
description: >
Unique and immutable username which is associated with the apikey.
Requires `x-rockit-tenant`, `x-rockit-orgname` and
`x-rockit-api-key`.
required: true
example: adminPrincipal
schema:
type: string
- name: x-rockit-api-key
in: header
description: >
Unique and immutable username which is associated with the apikey.
Requires `x-rockit-tenant`, `x-rockit-orgname` and
`x-rockit-api-key`.
required: true
example: '{{_adminPrincipal_apiKey}}'
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Unique and immutable identifier of the subscription.
sender:
type: string
description: Specify the issuer of the event.
enum:
- dltar
- mkraw
- deploy
x-apidog-enum:
- value: dltar
name: ''
description: >-
Subscribe to events of the game build import request
tasks
- value: mkraw
name: ''
description: Subscriptions to the ROCKIT image builder task
- value: deploy
name: ''
description: Subscribe to events of the publish tasks
event:
type: string
description: >-
Subscribe to a single event. This field is mutally excluded
with `events`.
enum:
- submit
- begin
- end
- error
- exception
x-apidog-enum:
- value: submit
name: ''
description: subscribe to the task submit event
- value: begin
name: ''
description: receive notification when the task starts
- value: end
name: ''
description: receive notification when the task ends
- value: error
name: ''
description: receive notification if the task fails
- value: exception
name: ''
description: receive notification if the task has an exception
events:
type: array
items:
type: string
enum:
- submit
- begin
- end
- error
- exception
x-apidog-enum:
- value: submit
name: ''
description: >-
receive notifications when the task is being added to
the processing queue.
- value: begin
name: ''
description: receive notification when the task starts
- value: end
name: ''
description: receive notification when the task is finished
- value: error
name: ''
description: receive notification when the task fails
- value: exception
name: ''
description: >-
receive notification when the task encounters an
exception
description: >
Supports Items such as 'submit', 'begin', 'end',
'exception', 'error'
description: Subscribe to a set of events.
type:
type: string
description: Notification type.
enum:
- webhook
- slack
x-apidog-enum:
- value: webhook
name: ''
description: Send notification by webhook. Requires `url`
- value: slack
name: ''
description: >-
Send notification by posting a Slack message. Requires
`slackToken` and `channelId`
url:
type: string
description: Target webhook URL. Required for `type`=`webhook`.
slackToken:
type: string
description: Slack token. Required for `type`=`slack`.
channelId:
type: string
description: Destination Slack channel. Required for `type`=`slack`.
x-apidog-orders:
- name
- sender
- event
- events
- type
- url
- slackToken
- channelId
required:
- name
- sender
- event
- events
- type
x-apidog-ignore-properties: []
example:
name: testSubscription
sender: dltar
events:
- submit
- begin
- end
- error
- exception
type: webhook
url: http://example.com/webhook
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: >-
A string confirming that the subscription request was
successful.
message:
type: string
description: >-
A confirmation message indicating that the subscription to
specific events (e.g., events such as "end", "error",
"exception" for a webhook or "submit", "begin", etc.) has
been established.
secret:
type: string
description: >-
Base64 encoded secret to verify the JWT send with the
webhook header `x-rockit-subscriptions`
required:
- status
- message
- secret
x-apidog-orders:
- status
- message
- secret
x-apidog-ignore-properties: []
examples:
'1':
summary: Subscribing a Webhook
value:
status: success
message: subscribed to events [end,error,exception]
secret: >-
bFJ6O0kuQGRyaEV0aDMsRI2JDRRcWVNN3E0T295Umg3LDg5JXpubUZZcG1zdigjKSTVCbw==
'2':
summary: Subscribing a Slack channel
value:
status: success
message: subscribed to events [submit,begin,end,error,exception]
headers: {}
x-apidog-name: Success
'400':
description: ''
content:
application/json:
schema:
title: ''
type: object
properties:
status:
type: string
description: >-
Reflects that the creation failed due to one or more
invalid or missing parameters in the request.
error:
type: string
description: Contains an error identifier. (e.g., "invalid-param")
message:
type: string
description: >-
Explains the nature of the invalid input (for example,
"name invalid").
detail:
type: string
description: >-
Offers further context on the error. (e.g., expected
pattern for the organization name)
x-apidog-orders:
- 01JQNHZ8P7G2HZRS1G057EE0VA
required:
- status
- error
- message
- detail
x-apidog-refs:
01JQNHZ8P7G2HZRS1G057EE0VA:
$ref: '#/components/schemas/Invalid%20Param'
x-apidog-ignore-properties:
- status
- error
- message
- detail
headers: {}
x-apidog-name: Invalid Param
'401':
description: ''
content:
application/json:
schema:
title: ''
type: object
properties:
status:
type: string
description: >-
Indicates that the organization creation request was
rejected because of authentication problems.
error:
type: string
description: Contains an error identifier. (e.g."unauthorized")
message:
type: string
description: >-
Provides details such as "invalid token" to help diagnose
the failure.
x-apidog-orders:
- 01JQNHZPMJGKPPR7HFG65ZD40E
required:
- status
- error
- message
x-apidog-refs:
01JQNHZPMJGKPPR7HFG65ZD40E:
$ref: '#/components/schemas/unauthorized'
x-apidog-ignore-properties:
- status
- error
- message
headers: {}
x-apidog-name: Unauthorized
'409':
description: ''
content:
application/json:
schema:
title: ''
type: object
properties:
status:
type: string
description: >-
Indicates that the request failed because an organization
with the same identifier already exists or is protected.
error:
type: string
description: Contains an error identifier. (e.g., "item exists")
message:
type: string
description: >-
States that the organization cannot be created due to a
conflict.
detail:
type: string
description: Provides additional context.
x-apidog-orders:
- 01JQNJ0J4XRJDP1Z4MJHQWC3Z6
required:
- status
- error
- message
- detail
x-apidog-refs:
01JQNJ0J4XRJDP1Z4MJHQWC3Z6:
$ref: '#/components/schemas/Item-exists'
x-apidog-ignore-properties:
- status
- error
- message
- detail
headers: {}
x-apidog-name: Item exists
security: []
x-apidog-folder: ROCKIT Edge - Backend API/Subscriptions
x-apidog-status: released
x-run-in-apidog: https://app.apidog.com/web/project/732774/apis/api-14052754-run
components:
schemas:
Invalid Param:
type: object
properties:
status:
type: string
description: >-
Reflects that the creation failed due to one or more invalid or
missing parameters in the request.
error:
type: string
description: Contains an error identifier. (e.g., "invalid-param")
message:
type: string
description: >-
Explains the nature of the invalid input (for example, "name
invalid").
detail:
type: string
description: >-
Offers further context on the error. (e.g., expected pattern for the
organization name)
required:
- status
- error
- message
- detail
x-apidog-orders:
- status
- error
- message
- detail
x-apidog-ignore-properties: []
x-apidog-folder: ''
unauthorized:
type: object
properties:
status:
type: string
description: >-
Indicates that the organization creation request was rejected
because of authentication problems.
error:
type: string
description: Contains an error identifier. (e.g."unauthorized")
message:
type: string
description: >-
Provides details such as "invalid token" to help diagnose the
failure.
required:
- status
- error
- message
x-apidog-orders:
- status
- error
- message
x-apidog-ignore-properties: []
x-apidog-folder: ''
Item-exists:
type: object
properties:
status:
type: string
description: >-
Indicates that the request failed because an organization with the
same identifier already exists or is protected.
error:
type: string
description: Contains an error identifier. (e.g., "item exists")
message:
type: string
description: States that the organization cannot be created due to a conflict.
detail:
type: string
description: Provides additional context.
required:
- status
- error
- message
- detail
x-apidog-orders:
- status
- error
- message
- detail
x-apidog-ignore-properties: []
x-apidog-folder: ''
securitySchemes:
Bearer token:
type: bearer
scheme: bearer
description: >-
Enter your Access Token. You can obtain this by calling the /be/v1/login
endpoint. Use the Refresh token to get a new Access token when it
expires.
servers:
- url: https://Example-Server.com
description: Default
security: []
```