ROCKITPLAY API
  1. Subscriptions
ROCKITPLAY API
  • ROCKIT Edge - Admin API
    • Minimal Tests
      • ping
      • submit test task
    • Admin Edge Organizations
      • Create Organization
      • Delete Organization
  • ROCKIT Edge - Backend API
    • Backend Edge Organizations
      • Create Organization
      • Delete Organization
    • Authentication
      • user login
      • authentication
    • Account Management
      • get user details
      • list users
      • Modify user
      • delete users
      • Create User / Create Machine User
    • Deployments
      • Creating Deployments
      • Get Deployments
      • Get Deployment Details
      • Modify Deployment
      • Deleting Deployments
    • Apps
      • Creating Apps
      • Import native builds
      • App Details
      • List Apps
      • patch app
      • Delete Apps
    • Triggers
      • Process Traces
      • Retry Task
    • Tasks
      • Listing Tasks
      • Task Details
      • Acknowledge Warning / Expire Task
    • Subscriptions
      • Subscribe
        POST
      • List Subscriptions
        GET
      • Unsubscribe
        DELETE
    • Roles
      • List Roles
      • Create Role
      • Patch Role
      • Role Details
      • Delete Roles
  • Changelog
    • Changelog
  1. Subscriptions

Subscribe

POST
https://Example-Server.com/be/v1/subscriptions
Last modified:2025-05-08 12:00:04
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 HeaderDescriptions
Content-typeapplication/json
x-rockit-subscriptionsJWT can be verified with the secret obtained from POST /be/v1/subscriptions.
Webhook Request Body
type
enum<string> 
required
Allowed values:
dltarmkrawdeploy
event
enum<string> 
required
name
Allowed values:
submitbeginenderror
orgName
string 
required
The unique and immutable organization identifier which the app belongs to.
appName
string 
required
The unique and immutable identifier of the app.
exception
object 
optional
A non-blocking exception has occurred.
httpDownloadFailed
object 
optional
Download from the provided URL failed. Can be triggered by dltar.
fileReadFailed
object 
optional
The downloaded file has wrong type or is corrupted. Can be triggered by mkraw.
error
object 
optional
A blocking error occurred. Requires user action to be resolved. Can be triggered by deploy.
deployment
object 
optional
identifier of the deployment to which data could not be copied.
The token validation in with NodeJS might look like:

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 for more details.

Request

Header Params
x-rockit-beauth-token
string 
optional
ROCKIT Edge backend authentication token (POST /be/v1/auth) or API key (POST /be/v1/apikeys)
Mutually excluded with x-rockit-api-key.
Example:
{{_edge_org_admin_beauth_token}}
x-rockit-orgname
string 
optional
Unique and immutable organization identifier obtained from the ROCKIT Edge administrator.
Requires x-rockit-username and x-rockit-api-key.
Example:
{{EDGE_ORG_NAME}}
x-rockit-username
string 
optional
Unique and immutable username which is accociated with the apikey.
Requires x-rockit-orgname and x-rockit-api-key.
Example:
adminPrincipal
x-rockit-api-key
string 
optional
Unique and imuutable apikey which is accociated with an machine user.
Mutually excluded with x-rockit-beauth-token. Requires x-rockit-username and x-rockit-orgname.
Example:
{{_adminPrincipal_apiKey}}
Body Params application/json
name
string 
required
Unique and immutable identifier of the subscription.
sender
enum<string> 
required
Specify the issuer of the event.
Allowed values:
dltarmkrawdeploy
event
enum<string> 
required
Subscribe to a single event. This field is mutally excluded with events.
Allowed values:
submitbeginsuccesserror
events
array[string]
required
Subscribe to a set of events.
Allowed values:
submitbeginsuccesserror
type
enum<string> 
required
Notification type.
Allowed values:
webhookslack
url
string 
optional
Target webhook URL. Required for type=webhook.
slackToken
string 
optional
Slack token. Required for type=slack.
channelId
string 
optional
Destination Slack channel. Required for type=slack.
Example
{
  "name": "testSubscription",
  "sender": "dltar",
  "events": [
    "submit",
    "begin",
    "progress",
    "end",
    "exception",
    "error"
  ],
  "type": "webhook",
  "url": "http://example.com/webhook"
}

Request samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://Example-Server.com/be/v1/subscriptions' \
--header 'x-rockit-beauth-token: eyjhvcIhvds;huVODV...' \
--header 'x-rockit-orgname: ExampleOrg' \
--header 'x-rockit-username: adminPrincipal' \
--header 'x-rockit-api-key: {{_adminPrincipal_apiKey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "testSubscription",
    "sender": "dltar",
    "events": [
        "submit",
        "begin",
        "progress",
        "end",
        "exception",
        "error"
    ],
    "type": "webhook",
    "url": "http://example.com/webhook"
}'

Responses

🟢200Success
application/json
Body
status
string 
required
A string confirming that the subscription request was successful.
message
string 
required
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
string 
required
Base64 encoded secret to verify the JWT send with the webhook header x-rockit-subscriptions
Examples
{
  "status": "success",
  "message": "subscribed to events [end,error,exception]",
  "secret": "bFJ6O0kuQGRyaEV0aDMsRI2JDRRcWVNN3E0T295Umg3LDg5JXpubUZZcG1zdigjKSTVCbw=="
}
🟠400Invalid Param
🟠401Unauthorized
🟠409Item exists
Previous
Acknowledge Warning / Expire Task
Next
List Subscriptions
Built with