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

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

Body Params application/json

Example
{
    "name": "testSubscription",
    "sender": "dltar",
    "events": [
        "submit",
        "begin",
        "progress",
        "end",
        "exception",
        "error"
    ],
    "type": "webhook",
    "url": "http://example.com/webhook"
}

Request Code 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

Examples
{
    "status": "success",
    "message": "subscribed to events [end,error,exception]",
    "secret": "bFJ6O0kuQGRyaEV0aDMsRI2JDRRcWVNN3E0T295Umg3LDg5JXpubUZZcG1zdigjKSTVCbw=="
}
🟠400Invalid Param
🟠401Unauthorized
🟠409Item exists
Modified at 2025-05-08 12:00:04
Previous
Acknowledge Warning / Expire Task
Next
List Subscriptions
Built with