Data Push Webhook

Version V1

---

Molecule can push operational data to the partner as soon as it becomes available. This webhook is separate from the execution-response webhook and is used exclusively for real-time or near-real-time data delivery.

Partners must provide a URL that accepts HTTPS POST requests.

This webhook is used for:

• Telemetry updates
• Device health or status (Future)
• Market participation metrics (Future)
• Multi-device performance data (Future)
• Any recurring or event-driven reporting (Future)

Molecule sends data for one or more downstream devices in a single payload.

---

Endpoint (Partner-Hosted)

Example:

POST https://<partner-domain>/<API version>/<webhook>/<url>

Molecule will POST data to this endpoint whenever new data is available.

---

Payload Structure

Top-Level Fields

Field	Type	Description
timestamp	datetime	Time the data snapshot was generated (ISO-8601 UTC).
molecule_id	string	Unique identifier for the Molecule site or controller.
devices	array	List of device-level data objects.

Device Object Fields

Field	Type	Description
device_id	string	Identifier of the downstream device (inverter, relay, meter, etc.).
metrics	object	Key-value pairs representing telemetry or operational data for that device.

---

Sample Data Delivery Payload

{
  "timestamp": "2024-01-05T01:05:00Z",
  "molecule_id": "fecd0001c031e7e8",
  "devices": [
    {
      "device_id": "20000",
      "metrics": { 
        "state_of_charge": 82.5,
        "power_output": 4.8,
        "temperature": 32.1
      }
    },
    {
      "device_id": "21000",
      "metrics": {
        "relay_state": "closed",
        "last_switch_time": "2024-01-05T01:00:30Z"
      }
    },
    {
      "device_id": "22000",
      "metrics": {
        "voltage": 239.4,
        "frequency": 49.98
      }
    }
  ]
}

---

Authentication

Molecule includes the partner-configured authentication headers (e.g., X-API-Key, custom headers) when sending data to this webhook.

Partners must validate these headers to ensure the request originated from Molecule.

---

Delivery Expectations

• Partners must return 200 OK to confirm receipt.
• If a non-200 response is returned, Molecule may retry delivery depending on configuration.
• Payloads may include multiple devices and variable metric sets depending on what data is available at the time.
• Delivery is event-driven, not scheduled — Molecule pushes data as soon as it arrives.