API Reference
API Reference

Webhooks info

This webhook service supports various Smart Irrigation Controller, Smart Hose Timer, and Smart Lighting Controller events.

Webhook behavior and restrictions

Webhooks are created against a single resource (valve ID, irrigation controller ID, etc):

  • We allow up to 10 webhooks to be registered per resource at a time
  • A webhook may only be subscribed to event types which match the resource type. For example, you cannot create a webhook with a valve resource ID but a controller DEVICE_ZONE_RUN_STARTED_EVENT. Call the list webhook event types endpoint for valid event types.

When an event occurs, it is delivered as a POST to the registered URL. If a 5xx error is received, we will retry the POST call up to 5 times for the given event.

Webhooks which fail to receive 10 distinct events in a row are automatically deleted.

Webhook registration and event format

Webhooks are created with a POST request passing in the appropriate resourceId for the given eventTypes:

curl 'https://cloud-rest.rach.io/webhook/createWebhook' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ******' \
--data '{
    "resourceId": {
        "valveId": "98968402-0c18-4a42-9491-62e234741295"
    },
    "url": "https://webhook.site/0021d1c5-168c-4d3e-a7e4-d2a97deaf82e",
    "externalId": "valve-webhook",
    "eventTypes": [
        "VALVE_RUN_START_EVENT",
        "VALVE_RUN_END_EVENT"
    ]
}'

Each event is delivered with the same format:

{
  "eventId": "f5f20dc4-375e-377c-b3c7-4f9ea8a833b3",
  "eventType": "NO_SKIP_NOTIFICATION_EVENT",
  "externalId": "schedule-one",
  "payload": {
    // data specific to the event type
  },
  "resourceId": "85c309c6-ba69-4f90-8f3c-60e5ea3640fb",
  "resourceType": "IRRIGATION_CONTROLLER",
  "timestamp": "2024-12-19T19:33:47.528952Z"
}
  • The eventId is a unique UUID for the event and may be used to detect a duplicate delivery
  • The payload object contains fields specific to the event type. See example payloads for details.
  • The externalId field will be present if one has been set for the webhook registration record

Webhook authentication

When delivering an event to a registered webhook, we include a hex signature in the x-signature header which can be used to verify the event is in fact from Rachio's servers.

Using your API token as the shared secret, we compute an HMAC-SHA256 signature for the entire event request json body (omitting insignificant whitespace). Below are a few example signatures:

API token: 8f68fb5e-02e8-4b2d-adb0-d2fd1e59db6c
POST body: {"eventId":"6776d89e-b4e7-3f5a-864f-ba39e6bafa05","eventType":"FREEZE_SKIP_NOTIFICATION_EVENT","externalId":"schedule freeze webhook","payload":{"scheduleId":"0114b3b9-31fb-4fe8-aa0e-b4f60aac5f91","startTime":"2024-12-19T20:33:47.487367Z","tempC":"2.0","thresholdC":"7.0"},"resourceId":"85c309c6-ba69-4f90-8f3c-60e5ea3640fb","resourceType":"IRRIGATION_CONTROLLER","timestamp":"2024-12-19T19:33:47.487355Z"}
x-signature: 1056e2029f904e981ab76a2425853d90e7663b1bb8329a7c764f63f015be3092

API token: 10061589-b3e1-418e-a27d-d1bb4763a9ea
POST body: {"eventId":"6ace3fde-7f3d-316c-9a02-67f7d36ba6a3","eventType":"PROGRAM_RAIN_SKIP_CREATED_EVENT","payload":{"plannedRunStartTime":"2024-12-11T23:08:09Z"},"resourceId":"34e81383-6116-4604-be1c-b6e2dedebaef","resourceType":"PROGRAM","timestamp":"2024-12-11T22:18:00.445250Z"}
x-signature: 5daa5f6a301fce1d6f251096dd89c5c20809a80312b8d95ddf9c47da2ec5552f

API token: 0b6de780-6f47-410b-8c2a-c6e9c506f3f4
POST body: {"eventId":"e040e09b-3d09-3dca-a688-3b24401d53b0","eventType":"VALVE_RUN_START_EVENT","externalId":"123-123-123","payload":{"durationSeconds":"181","flowDetected":false,"programId":"48a7181c-e06e-4a4f-bd65-92567fce0b81","runType":"PROGRAM","startTime":"2024-12-11T20:20:48Z"},"resourceId":"205aa289-8fe0-4f8e-8fc2-032f5f1e1c24","resourceType":"VALVE","timestamp":"2024-12-11T20:20:52Z"}
x-signature: b8b1a1ee62542e3910c41f405371d5e419f30055f6ce07d776e8cbee84d7b14d

JSON keys in the request body are sorted alphabetically for a consistent signature.

Webhook event types and notes

The most up to date event availability can be retrieved from the list webhook event types call. Specific notes and examples are provided here.


Smart Hose Timer Programs

PROGRAM_RAIN_SKIP_CREATED_EVENT Occurs when a program rain skip has been created due to weather. One event is sent for each planned run that will be skipped for the day.
  • plannedRunStartTime includes the timestamp of the run to be skipped
PROGRAM_RAIN_SKIP_CANCELED_EVENT Occurs when weather has changed, and a previously created rain skip has been removed
  • plannedRunStartTime includes the timestamp of the run which will no longer be skipped

Smart Hose Timer Valves

VALVE_RUN_START_EVENT Occurs when a valve opens
  • durationSeconds reports the amount of time the valve will be open
  • flowDetected may be used to determine if the valve has flow or not.
  • runType is one of BUTTON_PRESS, QUICK_RUN, or PROGRAM and represents why the valve opened
  • programIdincludes the ID of the program which opened this valve and is present only when runType is PROGRAM
VALVE_RUN_END_EVENT Occurs when a valve closes
  • durationSeconds reports how long the valve was open before closing
  • endReason is one of COMPLETED or STOPPED depending on if the valve ran to completion or was prematurely stopped / closed
  • flowDetected may be used to determine if the valve had flow or not.
  • runType is one of BUTTON_PRESS, QUICK_RUN, or PROGRAM and represents why the valve opened
  • programIdincludes the ID of the program which opened this valve and is present only when runType is PROGRAM

Smart Irrigation Controller

SCHEDULE_STARTED_EVENT Occurs when a schedule begins
  • durationSeconds is the total time the schedule will run
  • startTime reports the timestamp this schedule run started
  • endTime is the timestamp when this schedule run will complete
  • runType is one of MANUAL or SCHEDULED depending on whether this schedule started due to a manual quick run
  • scheduleId reports the ID of the starting schedule
SCHEDULE_STOPPED_EVENT Occurs when a schedule is stopped before completion
  • durationSeconds is the total time the schedule ran
  • startTime reports the timestamp this schedule run started
  • endTime is the timestamp when this schedule was prematurely stopped
  • runType is one of MANUAL or SCHEDULED depending on whether this schedule run started due to a manual quick run
  • scheduleId reports the ID of the stopped schedule
SCHEDULE_COMPLETED_EVENT Occurs when a schedule has finished
  • durationSeconds is the total time the schedule ran
  • startTime reports the timestamp this schedule run completed
  • endTime is the timestamp when this schedule completed
  • runType is one of MANUAL or SCHEDULED depending on whether this schedule run started due to a manual quick run
  • scheduleId reports the ID of the completed schedule
DEVICE_ZONE_RUN_STARTED_EVENT Occurs when a zone begins watering
  • durationSeconds is the total time this zone will water
  • startTime reports the timestamp this zone began watering
  • endTime is the timestamp this zone run will complete
  • runType is one of MANUAL or SCHEDULED depending on whether this zone started due to a manual command or a schedule
  • zoneNumber reports the number of the zone which has started
  • flowVolumeG is the current volume reading in gallons from a flow meter if one is configured and connected to the controller
DEVICE_ZONE_RUN_STOPPED_EVENT Occurs when a watering zone is stopped before completion
  • durationSeconds is the total time this zone watered
  • startTime reports the timestamp this zone began watering
  • endTime is the timestamp this zone run was stopped
  • runType is one of MANUAL or SCHEDULED depending on whether this zone started due to a manual command or a schedule
  • zoneNumber reports the number of the zone which has started
  • flowVolumeG is the current volume reading in gallons from a flow meter if one is configured and connected to the controller
DEVICE_ZONE_RUN_COMPLETED_EVENT Occurs when a zone has completed watering
  • durationSeconds is the total time this zone watered
  • startTime reports the timestamp this zone began watering
  • endTime is the timestamp this zone run completed
  • runType is one of MANUAL or SCHEDULED depending on whether this zone started due to a manual command or a schedule
  • zoneNumber reports the number of the zone which has started
  • flowVolumeG is the current volume reading in gallons from a flow meter if one is configured and connected to the controller
DEVICE_ZONE_RUN_PAUSED_EVENT Occurs when a watering zone has been paused
  • durationSeconds is the remaining time the zone has to water
  • startTime reports the timestamp this zone will begin watering again
  • endTime is the timestamp the zone will complete watering after it resumes
  • runType is one of MANUAL or SCHEDULED depending on whether this zone started due to a manual command or a schedule
  • zoneNumber reports the number of the zone which has started
  • flowVolumeG is the current volume reading in gallons from a flow meter if one is configured and connected to the controller
CLIMATE_SKIP_NOTIFICATION_EVENT Occurs when a future schedule run will be skipped due to soil saturation, and again when that skipped run time arrives
  • scheduleId is the ID of the schedule which will be skipped
  • startTime is the timestamp of the run which will be skipped
FREEZE_SKIP_NOTIFICATION_EVENT Occurs when a future schedule run will be skipped due to temperature, and again when that skipped run time arrives
  • scheduleId is the ID of the schedule which will be skipped
  • startTime is the timestamp of the run which will be skipped
  • tempC is the measured temperature in celsius
  • thresholdC is the configured threshold for skips in celsius
WIND_SKIP_NOTIFICATION_EVENT Occurs when a future schedule run will be skipped due to wind, and again when that skipped run time arrives
  • scheduleId is the ID of the schedule which will be skipped
  • startTime is the timestamp of the run which will be skipped
  • windKph is the measured wind speed in kilometers per hour
  • thresholdKph is the configured threshold for skips in kilometers per hour
RAIN_SKIP_NOTIFICATION_EVENT Occurs when a future schedule run will be skipped due to rain, and again when that skipped run time arrives
  • scheduleId is the ID of the schedule which will be skipped
  • startTime is the timestamp of the run which will be skipped
  • observedMm is the observed precipitation in millimeters
  • predictedMm is the forecasted precipitation in millimeters
  • thresholdMm is the configured threshold for skips in millimeters
NO_SKIP_NOTIFICATION_EVENT Occurs when a previously discovered skip has been canceled due to weather changes
  • scheduleId is the ID of the schedule which will be skipped
  • startTime is the timestamp of the run which will be skipped

Smart Lighting Controller

LIGHTING_ZONE_STATE_CHANGE_EVENT Occurs when a lighting zone has changed state, whether it has changed between ON / OFF or adjusted its dimming level
  • reason denotes why the zone changed state and is one of BUTTON_PRESS, LIGHTING_PROGRAM, MATTER_COMMAND, or SERVER_COMMAND
  • lightingProgramId includes the ID of the lighting program which caused the state change. Only present if the reason is LIGHTING_PROGRAM
  • zoneNumberincludes the number of the zone which changed state
  • newState is the new state of the zone and is one of ON or OFF
  • previousState is the previous state of the zone and is one of ON or OFF
  • newDimmingPercent is the new dimming level of the zone
  • previousDimmingPercent is the previous dimming level of the zone

Example event data

Smart Hose Timer Programs:
PROGRAM_RAIN_SKIP_CREATED_EVENT:
{
  "eventId": "6ace3fde-7f3d-316c-9a02-67f7d36ba6a3",
  "eventType": "PROGRAM_RAIN_SKIP_CREATED_EVENT",
  "externalId": "Program hook",
  "payload": {
    "plannedRunStartTime": "2024-12-11T23:08:09Z"
  },
  "resourceId": "34e81383-6116-4604-be1c-b6e2dedebaef",
  "resourceType": "PROGRAM",
  "timestamp": "2024-12-11T22:18:00.445250Z"
}

PROGRAM_RAIN_SKIP_CANCELED_EVENT
{
  "eventId": "55d6deb6-67fd-3b78-ad74-99d90bd1b23c",
  "eventType": "PROGRAM_RAIN_SKIP_CANCELED_EVENT",
  "externalId": "Program hook",
  "payload": {
    "plannedRunStartTime": "2024-12-11T23:08:09Z"
  },
  "resourceId": "34e81383-6116-4604-be1c-b6e2dedebaef",
  "resourceType": "PROGRAM",
  "timestamp": "2024-12-11T22:33:00.473868Z"
}

Smart Hose Timers:
VALVE_RUN_START_EVENT (quick run)
{
  "eventId": "5b40e608-5837-38d7-aafa-79cea2f2a47a",
  "eventType": "VALVE_RUN_START_EVENT",
  "externalId": "123-123-123-external",
  "payload": {
    "durationSeconds": "360",
    "flowDetected": false,
    "runType": "QUICK_RUN",
    "startTime": "2024-12-11T22:21:35Z"
  },
  "resourceId": "205aa289-8fe0-4f8e-8fc2-032f5f1e1c24",
  "resourceType": "VALVE",
  "timestamp": "2024-12-11T22:21:39Z"
}

VALVE_RUN_START_EVENT (program)
{
  "eventId": "e040e09b-3d09-3dca-a688-3b24401d53b0",
  "eventType": "VALVE_RUN_START_EVENT",
  "externalId": "123-123-123-external",
  "payload": {
    "durationSeconds": "181",
    "flowDetected": false,
    "programId": "48a7181c-e06e-4a4f-bd65-92567fce0b81",
    "runType": "PROGRAM",
    "startTime": "2024-12-11T20:20:48Z"
  },
  "resourceId": "205aa289-8fe0-4f8e-8fc2-032f5f1e1c24",
  "resourceType": "VALVE",
  "timestamp": "2024-12-11T20:20:52Z"
}

VALVE_RUN_END_EVENT
{
  "eventId": "15085bc0-4ac5-3105-912a-4fc6340e4354",
  "eventType": "VALVE_RUN_END_EVENT",
  "externalId": "Valve one hook",
  "payload": {
    "durationSeconds": "51",
    "endReason": "STOPPED",
    "flowDetected": false,
    "runType": "QUICK_RUN",
    "startTime": "2024-12-11T22:21:35Z"
  },
  "resourceId": "205aa289-8fe0-4f8e-8fc2-032f5f1e1c24",
  "resourceType": "VALVE",
  "timestamp": "2024-12-11T22:22:30Z"
}

Smart Irrigation Controllers:
SCHEDULE_STARTED_EVENT
{
  "eventId": "8928d11c-ab36-3b36-ac35-ce77be24e2bc",
  "eventType": "SCHEDULE_STARTED_EVENT",
  "externalId": "Zone and skip hook",
  "payload": {
    "durationSeconds": "960",
    "endTime": "2024-12-19T20:06:02.386Z",
    "runType": "SCHEDULED",
    "scheduleId": "e8373d6c-a1b1-4432-ab2d-51826ae4c5f2",
    "startTime": "2024-12-19T19:50:02.386Z"
  },
  "resourceId": "85c309c6-ba69-4f90-8f3c-60e5ea3640fb",
  "resourceType": "IRRIGATION_CONTROLLER",
  "timestamp": "2024-12-19T19:50:01Z"
}

SCHEDULE_STOPPED_EVENT
{
  "eventId": "5b4c7b8b-d94b-31b2-bd1f-27a660db84b9",
  "eventType": "SCHEDULE_STOPPED_EVENT"
  "payload": {
    "durationSeconds": "171",
    "endTime": "2024-12-19T18:27:55.789Z",
    "runType": "SCHEDULED",
    "scheduleId": "0114b3b9-31fb-4fe8-aa0e-b4f60aac5f91",
    "startTime": "2024-12-19T18:25:04.789Z"
  },
  "resourceId": "85c309c6-ba69-4f90-8f3c-60e5ea3640fb",
  "resourceType": "IRRIGATION_CONTROLLER",
  "timestamp": "2024-12-19T18:27:54Z"
}

SCHEDULE_COMPLETED_EVENT
{
  "eventId": "a78dd02c-86fd-3f2c-ab5d-770f45c20181",
  "eventType": "SCHEDULE_COMPLETED_EVENT",
  "externalId": "schedule-one",
  "payload": {
    "durationSeconds": "124",
    "endTime": "2024-12-19T18:30:01.232Z",
    "runType": "MANUAL",
    "scheduleId": "0114b3b9-31fb-4fe8-aa0e-b4f60aac5f91",
    "startTime": "2024-12-19T18:27:57.232Z"
  },
  "resourceId": "85c309c6-ba69-4f90-8f3c-60e5ea3640fb",
  "resourceType": "IRRIGATION_CONTROLLER",
  "timestamp": "2024-12-19T18:29:57Z"
}

DEVICE_ZONE_RUN_STARTED_EVENT
{
  "eventId": "4ca8277a-28ac-362d-bf4d-46363568a05e",
  "eventType": "DEVICE_ZONE_RUN_STARTED_EVENT",
  "externalId": "Zone and skip hook",
  "payload": {
    "durationSeconds": "120",
    "endTime": "2024-12-19T19:45:34.685Z",
    "flowVolumeG": "0.0",
    "runType": "MANUAL",
    "startTime": "2024-12-19T19:43:34.685Z",
    "zoneNumber": "10"
  },
  "resourceId": "85c309c6-ba69-4f90-8f3c-60e5ea3640fb",
  "resourceType": "IRRIGATION_CONTROLLER",
  "timestamp": "2024-12-19T19:43:31Z"
}

DEVICE_ZONE_RUN_STOPPED_EVENT
{
  "eventId": "24fa35de-d93c-3491-afe3-79730ccafe7b",
  "eventType": "DEVICE_ZONE_RUN_STOPPED_EVENT",
  "externalId": "Zone and skip hook",
  "payload": {
    "durationSeconds": "21",
    "endTime": "2024-12-19T19:43:54.839Z",
    "flowVolumeG": "0.0",
    "runType": "MANUAL",
    "startTime": "2024-12-19T19:43:33.839Z",
    "zoneNumber": "10"
  },
  "resourceId": "85c309c6-ba69-4f90-8f3c-60e5ea3640fb",
  "resourceType": "IRRIGATION_CONTROLLER",
  "timestamp": "2024-12-19T19:43:52Z"
}

DEVICE_ZONE_RUN_COMPLETED_EVENT
{
  "eventId": "d37c79b5-a78a-3cb6-b6f2-df5fe63efa52",
  "eventType": "DEVICE_ZONE_RUN_COMPLETED_EVENT",
  "externalId": "zone-123-234",
  "payload": {
    "durationSeconds": "120",
    "endTime": "2024-12-19T17:55:02.971Z",
    "flowVolumeG": "23.1",
    "runType": "SCHEDULED",
    "startTime": "2024-12-19T17:53:02.971Z",
    "zoneNumber": "1"
  },
  "resourceId": "85c309c6-ba69-4f90-8f3c-60e5ea3640fb",
  "resourceType": "IRRIGATION_CONTROLLER",
  "timestamp": "2024-12-19T17:55:00Z"
}

DEVICE_ZONE_RUN_PAUSED_EVENT
{
  "eventId": "761d1112-1251-383f-a9f3-2d64611745c8",
  "eventType": "DEVICE_ZONE_RUN_PAUSED_EVENT",
  "payload": {
    "durationSeconds": "48",
    "endTime": "2024-12-19T18:42:03.901Z",
    "flowVolumeG": "0.0",
    "runType": "SCHEDULED",
    "startTime": "2024-12-19T18:41:15.901Z",
    "zoneNumber": "1"
  },
  "resourceId": "85c309c6-ba69-4f90-8f3c-60e5ea3640fb",
  "resourceType": "IRRIGATION_CONTROLLER",
  "timestamp": "2024-12-19T18:26:13Z"
}

CLIMATE_SKIP_NOTIFICATION_EVENT
{
  "eventId": "49b17777-67e2-3bbd-9ac4-51591dcf3c43",
  "eventType": "CLIMATE_SKIP_NOTIFICATION_EVENT",
  "payload": {
    "scheduleId": "0114b3b9-31fb-4fe8-aa0e-b4f60aac5f91",
    "startTime": "2024-12-20T07:33:47.224414Z"
  },
  "resourceId": "85c309c6-ba69-4f90-8f3c-60e5ea3640fb",
  "resourceType": "IRRIGATION_CONTROLLER",
  "timestamp": "2024-12-19T19:33:47.224384Z"
}

FREEZE_SKIP_NOTIFICATION_EVENT
{
  "eventId": "6776d89e-b4e7-3f5a-864f-ba39e6bafa05",
  "eventType": "FREEZE_SKIP_NOTIFICATION_EVENT",
  "externalId": "schedule-one",
  "payload": {
    "scheduleId": "0114b3b9-31fb-4fe8-aa0e-b4f60aac5f91",
    "startTime": "2024-12-19T20:33:47.487367Z",
    "tempC": "2.0",
    "thresholdC": "7.0"
  },
  "resourceId": "85c309c6-ba69-4f90-8f3c-60e5ea3640fb",
  "resourceType": "IRRIGATION_CONTROLLER",
  "timestamp": "2024-12-19T19:33:47.487355Z"
}

WIND_SKIP_NOTIFICATION_EVENT
{
  "eventId": "e9bc712d-37a6-31a3-bb99-e6431af4b600",
  "eventType": "WIND_SKIP_NOTIFICATION_EVENT",
  "payload": {
    "scheduleId": "0114b3b9-31fb-4fe8-aa0e-b4f60aac5f91",
    "startTime": "2024-12-19T20:33:47.522032Z",
    "thresholdKph": "32.0",
    "windKph": "35.0"
  },
  "resourceId": "85c309c6-ba69-4f90-8f3c-60e5ea3640fb",
  "resourceType": "IRRIGATION_CONTROLLER",
  "timestamp": "2024-12-19T19:33:47.522025Z"
}


RAIN_SKIP_NOTIFICATION_EVENT
{
  "eventId": "8594280d-8c09-3aa0-8ca7-0d6384003ee6",
  "eventType": "RAIN_SKIP_NOTIFICATION_EVENT",
  "payload": {
    "observedMm": "22.1",
    "predictedMm": "2.2",
    "scheduleId": "0114b3b9-31fb-4fe8-aa0e-b4f60aac5f91",
    "startTime": "2024-12-20T07:33:47.508222Z",
    "thresholdMm": "19.0"
  },
  "resourceId": "85c309c6-ba69-4f90-8f3c-60e5ea3640fb",
  "resourceType": "IRRIGATION_CONTROLLER",
  "timestamp": "2024-12-19T19:33:47.508212Z"
}

NO_SKIP_NOTIFICATION_EVENT
{
  "eventId": "f5f20dc4-375e-377c-b3c7-4f9ea8a833b3",
  "eventType": "NO_SKIP_NOTIFICATION_EVENT",
  "payload": {
    "scheduleId": "0114b3b9-31fb-4fe8-aa0e-b4f60aac5f91",
    "startTime": "2024-12-19T20:33:47.528961Z"
  },
  "resourceId": "85c309c6-ba69-4f90-8f3c-60e5ea3640fb",
  "resourceType": "IRRIGATION_CONTROLLER",
  "timestamp": "2024-12-19T19:33:47.528952Z"
}

Smart Lighting Controllers:
LIGHTING_ZONE_STATE_CHANGE_EVENT
{
  "eventId": "188a0961-a925-32a8-a186-d889948aedeb",
  "eventType": "LIGHTING_ZONE_STATE_CHANGE_EVENT",
  "externalId": "SLC webhook",
  "payload": {
    "lightingProgramId": "42d6b17d-ed84-463c-83ae-8b5afedf8126",
    "newDimmingPercent": "100",
    "newState": "ON",
    "previousDimmingPercent": "0",
    "previousState": "OFF",
    "reason": "LIGHTING_PROGRAM",
    "zoneNumber": "2"
  },
  "resourceId": "438112f8-2e05-44bc-bb91-8faf808c1aa0",
  "resourceType": "LIGHTING_CONTROLLER",
  "timestamp": "2024-12-11T20:31:01Z"
}