Skip to main content

Site Command Webhook

Version V1​

MosVPP provides a secure HTTPS API for partners to submit site command requests to Molecule Systems. Partners can send site-level control commands to Molecule Systems using the following endpoint:

POST https://webhooks.moleculesystems.com/<API version>/api/gateway/<molecule_id>/sitecmd

Replace <molecule_id> with the unique identifier for the Molecule site or controller.

This endpoint is used to control downstream devices at a site — such as inverters, relays, or other DER components — through a single aggregated site command.

Molecule validates the request and responds synchronously with a receipt.

Site Command Payload Structure​

A site command consists of:

  • A site command ID (scmd_id)
  • A duration (scmd_secs)
  • A list of downstream device commands (scmd_devices)

Top-Level Fields​

FieldTypeDescription
scmd_typeguidSite command type. deviceControl
scmd_idguidUnique identifier for the site command. Must be a valid UUID.
scmd_secsintegerDuration of the command in seconds. Applies to all downstream devices.
scmd_devicesarrayList of device-specific commands for downstream devices (inverters, relays, etc.).

Downstream Device Fields (scmd_devices[])​

FieldTypeDescription
device_idstringIdentifier of the downstream device (e.g., inverter ID, relay ID).
cmd_typestringCommand type. Allowed values: charge, discharge, off, on, shed, restore.
cmd_quantityfloat (optional)Command magnitude (required for commands like charge/discharge).
cmd_unitstring (optional)Unit for cmd_quantity. Allowed values: w, kW, MW.
note

cmd_quantity and cmd_unit are required for power-based commands (charge, discharge, shed). They are not required for state-based commands (off, on, restore).

Sample Site Command Request​

{
  "scmd_type": "deviceControl",
  "scmd_id": "8A7DA4D3-5AD6-42F6-BCAD-6194BBD2F68D",
  "scmd_secs": 900,
  "scmd_devices": [
    {
      "device_id": "20000",
      "cmd_type": "discharge",
      "cmd_quantity": 5.0,
      "cmd_unit": "kW"
    },
    {
      "device_id": "21000",
      "cmd_type": "off"
    }
  ]
}

This example instructs:

  • Device 20000 → discharge at 5 kW for 900 seconds
  • Device 21000 → turn off for 900 seconds

Security Requirements​

The same security model applies as with dispatch requests.

IP Restrictions​

Access to webhooks.moleculesystems.com is restricted by IP. Partners must ensure their outbound IPs are on the Molecule allowlist.

API Key​

Partners must include the provided API key:

X-API-Key: <your-api-key>

Molecule Response​

Molecule responds synchronously with a receipt confirming the site command was accepted.

Sample Response​

{
  "status": "accepted",
  "scmd_id": "8A7DA4D3-5AD6-42F6-BCAD-6194BBD2F68D"
}

Response Fields​

FieldTypeDescription
statusstring"accepted" indicates successful processing.
scmd_idguidThe site command ID associated with the accepted request.

Authentication for Molecule → Partner​

If the partner has configured custom headers in the Molecule Developer Portal, Molecule will include them in the response.

Best Practices for Site Commands​

Idempotency​

  • Reuse the same scmd_id when retrying a failed request.
  • Molecule treats repeated commands with the same ID as the same request.

Device Capability Validation​

Partners should ensure:

  • The downstream device supports the requested cmd_type
  • Units and quantities are valid for that device type

Duration Management​

  • scmd_secs applies to all devices in the command.
  • If different durations are needed, send separate site commands.

Retry Logic​

  • Retry only on network or server errors.
  • Do not generate a new scmd_id for retries.

Time Synchronization​

  • Ensure partner systems and devices use synchronized clocks (NTP recommended).