Integrating Data Providers with Maestro

Introduction

Data Providers enable you to seamlessly integrate external data sources with the Maestro platform. This feature allows real-time data ingestion from various sources, enabling dynamic content updates, automation, and enhanced interactivity in your streams.

This guide covers how to register a new Data Provider and submit data events through the Maestro API.

What are Data Providers?

Data Providers are external systems that generate data which can be used within Maestro to trigger actions, update overlays, or automate channel creation. Examples include:

• Sports data and statistics
• Social media feeds
• IoT device data
• Custom application events
• Third-party APIs

Registering a Data Provider

Before sending data to Maestro, you must register your Data Provider through our API.

Registration Endpoint

POST https://api.maestro.io/dataprovider/v1/register

Request Headers

Content-Type: application/json

Request Body

Field	Type	Description	Required
name	string	Name of your Data Provider	Yes
description	string	Description of what this Data Provider does	Yes
schema	object	JSON Schema defining the structure of your data	Yes
ownerName	string	Name of the person responsible for this Data Provider	Yes
ownerEmail	string	Email of the person responsible for this Data Provider	Yes
realtime	boolean	Whether this provider sends real-time data	Yes
ttl	number	Time-to-live in seconds for the data (null for no expiration)	No

Schema Definition

The schema field uses JSON Schema to define the structure of data your provider will send. This ensures data validation and consistent structure.

Example schema:

{
  "type": "object",
  "properties": {
    "foo": {
      "type": "integer",
      "description": "An example integer field"
    },
    "bar": {
      "type": "string",
      "description": "An example string field"
    }
  },
  "required": ["foo"],
  "additionalProperties": false
}

Example Registration Request

curl --location 'https://api.maestro.io/dataprovider/v1/register' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "name": "New Data Provider",
      "description": "Description of the Data Provider",
      "schema": {
          "type": "object",
          "properties": {
              "foo": {
                  "type": "integer"
              },
              "bar": {
                  "type": "string"
              }
          },
          "required": [
              "foo"
          ],
          "additionalProperties": false
      },
      "ownerName": "John Doe",
      "ownerEmail": "johndoe@maestro.io",
      "realtime": true,
      "ttl": null
  }'

Response

Upon successful registration, you'll receive:

{
  "dataProviderId": "dp_1234567890abcdef",
  "secret": "sk_your_secret_api_key",
}

note

The secret will only be shown once. Store it securely as it will be needed to authenticate future data submissions.

Submitting Data Events

After registering your Data Provider, you can submit data events through the ingestion API.

Ingestion Endpoint

POST https://api.maestro.io/dataprovider/v1/{dataProviderId}/events

Replace {dataProviderId} with the ID received during registration.

Authentication

All data submissions must include an HMAC signature to verify the request origin:

1. The request must include an X-DataProvider-Signature header
2. The signature value is an HMAC-SHA256 hash of the request body, using the secret provided to you during registration.

Creating the Signature

Javascript

const crypto = require('crypto');
const secret = 'sk_your_secret_api_key';
const payload = JSON.stringify(requestBody);

const signature = crypto.createHmac('sha256', secret)
  .update(payload)
  .digest('hex');

Python

import hmac
import hashlib
import json

secret = 'sk_your_secret_api_key'
payload = json.dumps(request_body)

signature = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()

Request Headers

Content-Type: application/json
X-DataProvider-Signature: {calculated-signature}

Request Body

The request body must conform to the JSON Schema you defined during registration.

Example Data Submission Request

curl --location 'https://api.maestro.io/dataprovider/v1/dp_1234567890abcdef/events' \
  --header 'Content-Type: application/json' \
  --header 'X-DataProvider-Signature: a1b2c3d4e5f6...' \
  --data-raw '{
      "foo": 123,
      "bar": "helloworld"
  }'

Response

A successful submission will return:

{
  "success": true,
}

Error Handling

The API returns appropriate HTTP status codes and error messages:

• 400 Bad Request: Invalid payload format or schema validation failed
• 401 Unauthorized: Missing or invalid signature
• 403 Forbidden: Data Provider not found or access denied
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server-side error

Error response example:

{
  "success": false,
  "message": "Payload does not match the defined schema",
}

Best Practices

Security

• Store your secret securely and never expose it in client-side code
• Use HTTPS for all requests

Schema Design

• Define clear and specific schemas to ensure data quality
• Use appropriate data types and validations
• Include only necessary properties to minimize payload size

Next Steps

Once your Data Provider is registered and sending data, you can:

1. Create rules in Maestro to act on incoming data
2. Build dynamic overlays that react to real-time data