Demand Response Webhook

Version V1

---

MosVPP provides a secure HTTPS API for partners to submit dispatch requests to Molecule Systems. Each request may contain one or more dispatch events (charge, discharge, shed, restore). Molecule validates these requests and responds synchronously with a receipt.

This API is strictly partner → Molecule. Molecule does not push notifications through this endpoint.

---

Field Definitions

Dispatch Request Fields

Top-Level Fields

Field	Type	Description
mode	string	Indicates the type of request. Allowed values: "test" for test submissions, "live" for production dispatch requests.
event_slots	array	A list of dispatch event objects.

Event Fields

Field	Type	Description
event_id	guid	Unique identifier for the event. Must be a valid UUID.
start_time	datetime	Event start time in ISO-8601 UTC format.
end_time	datetime	Event end time in ISO-8601 UTC format. Must be later than start_time.
event_type	string	Allowed values: charge, discharge, shed, restore.
event_quantity	float	Magnitude of the event.
event_unit	string	Allowed values: w, kW, MW.
priority	integer	Event priority (1–99). Lower numbers represent higher priority.
mandatory	boolean	Indicates whether the event is compulsory under program rules.
cancelled	boolean	Indicates whether the event has been cancelled.

---

Sending Dispatch Requests to Molecule

Partners submit dispatch requests to:

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

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

Security Requirements

• Access to webhooks.moleculesystems.com is restricted by IP. Molecule will provide the required allowlist.
• Partners must include the provided API key:

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

Sample Dispatch Request

{
  "mode": "test",
  "event_slots": [
    {
      "event_id": "8A7DA4D3-5AD6-42F6-BCAD-6194BBD2F68D",
      "start_time": "2024-01-05T00:00:00Z",
      "end_time": "2024-01-05T01:00:00Z",
      "event_type": "discharge",
      "event_quantity": 5.0,
      "event_unit": "kW",
      "priority": 1,
      "mandatory": true,
      "cancelled": false
    }
  ]
}

---

Molecule Response (Receipt)

Molecule responds synchronously to each dispatch request with a receipt.

Sample Response

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

Authentication for Molecule → Partner

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

Example configuration:

{
  "headers": [
    { "name": "X-API-Key", "value": "Your-API-Key" },
    { "name": "X-API-Custom-Passthrough", "value": "Custom value" }
  ]
}

These headers are sent by Molecule to the partner's callback endpoint.

---

Execution Response Webhook (Partner-Hosted)

Once a dispatch event has been executed, Molecule sends an execution response to the partner's webhook. Partners must provide a URL that accepts HTTPS POST requests.

Payload Structure

Field	Type	Description
event_id	guid	The event identifier originally provided by the partner.
status	string	Execution status: completed, partial, failed.
timestamp	datetime	ISO-8601 UTC timestamp indicating when execution completed.
details	object (optional)	Additional execution information (e.g., delivered quantity, device-level results).

Sample Execution Response

{
  "event_id": "8A7DA4D3-5AD6-42F6-BCAD-6194BBD2F68D",
  "status": "completed",
  "timestamp": "2024-01-05T01:00:05Z",
  "details": {
    "delivered_quantity": 5.0,
    "delivered_unit": "kW"
  }
}

Authentication

Molecule includes the partner-configured headers when sending execution responses.

---

Best Practices

Idempotency

• Reuse the same event_id when retrying a failed request.
• Molecule treats repeated requests with the same ID as the same command.

Retry Logic

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

Time Synchronization

• All timestamps must be in UTC.
• Ensure devices and partner systems use synchronized clocks (NTP recommended).

Validation Before Sending

Partners should validate:

• start_time < end_time
• event_type is one of the allowed values
• Units and quantities are valid
• Priority is within 1–99

Security

• Keep your API key secret.
• Ensure outbound IPs match Molecule's allowlist.
• Use HTTPS only.

Testing

Use "mode": "test" for sandbox or integration testing.