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 sends an HTTP request from PrimeCal's servers. The target must be reachable from the internet over HTTPS. Systems that only listen on your home network cannot be called directly. It supports a configurable HTTP method and first-class authentication, which is exactly what most smart-home REST APIs (Home Assistant, Shelly, and similar) expect once exposed this way.

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://<your-instance>.ui.nabu.casa/api/webhook/<webhook-id>",
  "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.

PrimeCal refuses requests it cannot deliver safely

A Call Webhook request is rejected before it is sent when:

• the URL is not HTTPS,
• the host is localhost, ends in .local, or resolves to a private/internal IP address,
• the URL contains a username or password, or
• the server responds with a redirect.

A local-only Home Assistant instance (homeassistant.local, or any address only your home network can reach) fails every one of these. Expose it first — through Home Assistant Cloud (Nabu Casa) or your own reverse proxy with a valid certificate — and call its /api/webhook/<id> path instead.

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.

A ready-made Home Assistant blueprint for the other direction

The example above has PrimeCal calling Home Assistant. For the reverse — Home Assistant calling PrimeCal, or Home Assistant reacting to something PrimeCal sends it — download the PrimeCal Webhook Action blueprint and import it into Home Assistant (Settings → Automations & scenes → Blueprints → Import blueprint). It creates a webhook endpoint on the Home Assistant side and lets you pick any action to run when PrimeCal calls it, with the payload PrimeCal sent available as a template variable. See the Automation Recipes page for the matching actionConfig to put on the PrimeCal side.

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