Smart-Home Automation

PrimeCal automations can reach beyond the calendar and into your smart home in two ways: by calling a device's REST API directly, and by instantiating a routine template on demand from any trigger. Both build on existing automation building blocks — there's no separate "smart home" module to configure.

Calling A Smart-Home Device's REST API

The Call Webhook action already sends an HTTP request to a URL you configure. It now supports a configurable HTTP method and first-class authentication, which is exactly what most local smart-home REST APIs (Home Assistant, Shelly, and similar) expect.

Configuring The Request

In the action builder, the Call Webhook action exposes:

• Method — GET, POST, PUT, PATCH, or DELETE (defaults to POST if unset, for compatibility with rules saved before this field existed).
• Auth type — none, bearer, basic, or header:
  • bearer sends Authorization: Bearer <token>.
  • basic sends Authorization: Basic <base64(user:pass)> — provide the token already in user:pass form.
  • header sends the token under a custom header name you specify (useful for APIs that expect something like X-API-Key).
• A few common presets (Home Assistant REST command, Shelly relay toggle, generic Bearer-token endpoint) pre-fill sensible method/auth defaults so you don't have to remember them.

Example: Turn On A Washing Machine At Its Scheduled Start

The Lates have a "Start laundry" task inside a routine template. When that task reaches its scheduled start time, they want PrimeCal to call their Home Assistant instance and turn the washing machine's smart plug on.

Example actionConfig for the webhook action:

{
  "url": "https://homeassistant.local:8123/api/services/switch/turn_on",
  "method": "POST",
  "authType": "bearer",
  "authToken": "YOUR_HOME_ASSISTANT_LONG_LIVED_TOKEN",
  "customPayload": { "entity_id": "switch.washing_machine" }
}

The trigger for this rule is task.scheduled_start — it fires when a task (in this case, a task instantiated from a routine item) reaches its scheduled start time. This trigger isn't in the rule builder's trigger picker yet, so a rule like this is currently created directly through the Automation API (or by an MCP-connected agent) rather than from the UI dropdown.

Keep tokens out of shared rules

Auth tokens are stored as part of the action configuration. Treat a cloned or shared automation rule the same way you'd treat a shared credential — rotate the token if the rule is ever exported or copied somewhere you don't control.

Starting A Routine From Any Trigger

The instantiate_routine action lets any trigger — a webhook, a scheduled time, an event being created, a task's status changing, or a task reaching its scheduled start — kick off a routine template immediately, exactly as if you'd clicked Start now on it. See Routines and Templates for what a routine template is and the other two ways it can start.

Example: A Smart Alarm Clock Triggers Morning Routine

The Lates' smart alarm clock can POST a webhook when it goes off. Instead of manually opening PrimeCal and clicking Start now on "Morning Routine" every morning, they wire the alarm clock to a rule that instantiates it automatically.

Example actionConfig for the instantiate_routine action:

{
  "routineTemplateId": 42
}

Rule shape:

1. Trigger: webhook.incoming — the smart alarm clock's integration POSTs to the rule's webhook URL when it goes off. See Webhooks for how to find and send to that URL.
2. Action: instantiate_routine with routineTemplateId set to The Lates' cloned "Morning Routine" template.

The action reuses the same ownership check as the manual Start now button — a rule can only instantiate a routine template its owner can already see (their own templates, templates shared through their people group, or active system templates), never an arbitrary template ID belonging to someone else.

Like task.scheduled_start, the instantiate_routine action type isn't in the action picker's dropdown yet. Create or edit a rule through the Automation API to use it — for example with PUT /api/automation/rules/:id and an actions array containing { "actionType": "instantiate_routine", "actionConfig": { "routineTemplateId": 42 } }.

See Also

• Webhooks — finding and sending to a rule's webhook URL
• Actions Overview — the full list of action types
• Routines and Templates — what a routine template is and how rotation works
• Automation API — creating rules with task.scheduled_start, task.status_changed, and instantiate_routine directly

---

Last updated: 2026-07-05 | PrimeCal v1.3.44