Quick Start¶

Getting started with using Streaming APIs involves the following steps:

1. Obtain a JSON Web Token (JWT) for your machine user role.
2. Register webhook endpoints for real-time notifications.
3. Test webhook deliveries with sample events.

Note: In the following examples we are:

1. Making use of a Linux/MacOS shell in which environmental variables are set using the export-command. In other environments it may be different, e.g. Windows uses the set-command instead.
2. Using the curl as a client. But the API can be used in any programming language with an HTTP Client, e.g. Go, Python, NodeJS, Javascript and Java.

Authentication¶

o use the Streaming API, you need a valid JWT token with the required permissions. Please visit Authentication section to construct the Create Token request.

Using Your Token¶

Once you have obtained your JWT token, set it as an environment variable along with your partition ID and webhook configuration:

export PARTITION=<YOUR_PARTITION_ID>
export TOKEN=<YOUR_JWT_TOKEN>
export WEBHOOK_URL=<YOUR_WEBHOOK_ENDPOINT>
export WEBHOOK_SECRET=<YOUR_SECRET_KEY>  # Optional: for webhook signature verification

You can now use the token by passing it in the Authorization header of all API requests.

Make API requests¶

This guide will take you through the steps you need to perform to register webhooks and start receiving real-time notifications.

Register Point Stream Webhook¶

Before you can receive point data notifications, you need to register a webhook for specific sensor points. You can do so by executing the following request:

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://test-api.com/test/webhook",
    "pointIds": [
      "88d45219-a0cf-4509-8f3d-84d15e6a9c44"
    ],
    "webhookSecret": "webhook-secret-key"
  }' \
  "https://api.bpcloud.siemens.com/streaming/v1/partitions/$PARTITION/streams?type=point-stream"

Note: The webhookSecret field is optional. If omitted, webhook payloads will not include signature verification.

Example Response¶

{
  "id": "12345678-1234-1234-1234-123456789012",
  "type": "point-stream",
  "attributes": {
    "partitionId": "1bcaafc3-d4d3-43e1-ab64-89d8518d5951",
    "webhookUrl": "https://test-api.com/test/webhook",
    "pointIds": [
      "88d45219-a0cf-4509-8f3d-84d15e6a9c44"
    ],
    "status": "active",
    "createdAt": "2025-11-17T14:30:22Z",
    "updatedAt": "2025-11-17T14:30:22Z"
  }
}

The id is your stream identifier that you can use to manage this subscription later.

List Your Stream Subscriptions¶

To view all your registered webhooks:

# List point stream subscriptions
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.bpcloud.siemens.com/streaming/v1/partitions/$PARTITION/streams?type=point-streams"

Webhook Payload Examples¶

Once registered, your webhook endpoint will receive POST requests whenever point data changes occur. Each webhook delivery contains the updated point information in the following structure:

Point Data Event¶

When a point value changes, your webhook will receive a payload like this:

{
  "changed": 1,
  "createdAt": "2025-12-03T06:09:21.915Z",
  "id": "6360e1ef-18b5-457c-a488-47t4f4b60e29",
  "lastUpdatedAt": "2025-12-03T06:09:28.077Z",
  "qualityOfValue": 0,
  "value": "22"
}

Field Descriptions:

• changed: Indicates the change status (1 = changed, 0 = no change)
• createdAt: Timestamp when the point was initially created
• id: Unique identifier for the point
• lastUpdatedAt: Timestamp of the most recent update
• qualityOfValue: Quality indicator for the data (0 = good quality)
• value: The current value of the point

Your webhook endpoint must respond with a 2xx HTTP status code to acknowledge successful receipt. Failed deliveries will be retried and eventually sent to the Dead Letter Queue if they continue to fail.

Verify Webhook Signatures (Optional)¶

If you provided a webhook secret during registration, you can verify webhook signatures to ensure authenticity:

import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(f"sha256={expected_signature}", signature)

Manage Stream Subscriptions¶

You can get entities, add/remove entities, or delete your stream subscriptions as needed:

# Get all points in a point stream
curl -X GET \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.bpcloud.siemens.com/streaming/v1/partitions/$PARTITION/streams/$STREAM_ID/entities?type=point-streams"

# Add or update points in a point stream
curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pointIds": [
      "88d45219-a0cf-4509-8f3d-84d15e6a9c49"
    ]
  }' \
  "https://api.bpcloud.siemens.com/streaming/v1/partitions/$PARTITION/streams/$STREAM_ID/entities?type=point-streams"

# Remove specific points from a point stream
curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pointIds": [
      "88d45219-a0cf-4509-8f3d-84d15e6a9c49"
    ]
  }' \
  "https://api.bpcloud.siemens.com/streaming/v1/partitions/$PARTITION/streams/$STREAM_ID/entities?type=point-stream"

# Delete entire point stream subscription
curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.bpcloud.siemens.com/streaming/v1/partitions/$PARTITION/streams/$STREAM_ID?type=point-stream"

The GET operation returns a list of entities. The entity DELETE operation returns the updated stream. The stream DELETE operations return a 204 No Content response if successful.