Connecting fermentation sensors (Tilt, RAPT)
Floating hydrometers can push gravity and temperature straight into MakeWine over HTTP. Each fermentation batch gets its own webhook URLs and a private ingest token, so readings land on the right batch automatically. The Tilt Hydrometer is the fully supported device; RAPT Pill support is currently in beta.
Find your setup details
- Open the wine, then open the 📡 Hardware tab. If the wine has more than one batch, pick it from the Batch selector.
- Note the Fermentation ID in the callout. A Tilt does not need it — the token in the URL identifies the batch — but firmware that lets you shape the payload (RAPT) can send it. A batch that has a device reporting shows an Active — receiving readings badge; one that has not received any reading yet shows Ready — waiting for a device.
- For copy-paste URLs that already include your ingest token, go to Fermentations in the main navigation and press 📡 Sensor setup on the batch. You get one URL per device type (Tilt, RAPT) with a Copy button beside each.
The ingest token
Webhooks are public endpoints, so every push must carry the batch's ingest token — appended to the URL as ?token=... (most sensor firmwares let you set the full POST URL), sent as an X-Ingest-Token header, or, where the device builds the request for you, added as a query-string parameter (this is the RAPT case). Requests without a valid token are rejected with a 401. If a token leaks, press Rotate token in the sensor setup panel; existing devices will then need the new URL.
Configure your device
All three endpoints accept an HTTP POST with JSON:
| Device | Endpoint | Notes |
|---|---|---|
| Tilt Hydrometer | /api/webhooks/tilt?token=… | Paste the URL straight into the Tilt app's Cloud URL box — that is all it needs. The token identifies the batch, so nothing goes in the payload (the app builds its own and gives you no field to add one). The copy-paste URL ends in &unit=F. Leave it there even if your Tilt app displays Celsius: a Tilt always transmits Fahrenheit, and its Units setting only changes what the app shows you. We convert on arrival, so your readings chart in °C. A Tilt Pi or bridge that can shape its own body may still send fermentationId, gravity, temp, tempUnit. |
| RAPT Pill | /api/webhooks/rapt | Not a URL you paste — a form you fill in. RAPT's Url field will not accept a query string, so the token goes in as a separate Query String parameter (token). See Connecting a RAPT Pill for the whole setup. |
| Generic HTTP push | /api/webhooks/rapt?token=… | The same endpoint for anything else that can POST JSON. Send gravity, temperature (Celsius), tilt and optionally battery or batteryVolts. |
The 📡 Hardware tab shows a ready-made example payload for each device.
The RAPT Pill is the one that catches people out
Every other device here takes a single field: a URL with the token on the end. RAPT does not. It is configured through a Custom Webhook form with separate Url, Method, Payload and Parameters boxes, and it insists the Url arrives without a query string. Paste our tokened URL into it and the token is silently dropped — every reading comes back 401 while the setup looks perfectly correct.
So for a RAPT: bare URL, method POST, and the token added as a Query String parameter named token. The Hardware tab lays the fields out in the order RAPT asks for them, and the full RAPT guide covers the rest — including the setup hotspot password nobody tells you.
Watch the data arrive
Back on the 📡 Hardware tab, the Live Readings chart plots gravity and temperature over time. Once readings flow you also get summary figures for Current gravity, Temperature and Attenuation — a quick read on how far fermentation has progressed. Data typically appears within minutes of the first successful push.
Troubleshooting
- 401 response — the token is missing or wrong. Re-copy the URL from Sensor setup, or check the
X-Ingest-Tokenheader. - 410 response — the batch has finished recording. Nothing is wrong with the device: see Finishing a batch below.
- 400 "fermentation not found" — the
fermentationIdin the payload doesn't match an existing batch. - Nothing on the chart — confirm the device is POSTing JSON and that you're viewing the same batch in the Batch selector.
Finishing a batch
When a fermentation is over, press Stop recording on the batch. The button sits on the batch's own card in the 📡 Hardware tab, above the device cards — it governs every device feeding that batch, not one particular make of sensor. The device keeps its token — you are not revoking anything — but readings taken after that moment are answered 410 Gone.
That code is deliberate. "Invalid token" would send you checking a setup that is perfectly correct, and a collector would reasonably treat it as a permanent failure and bury it. 410 says the batch is deliberately over, which is what actually happened, and gives a well-behaved collector something to act on: stop scanning and ask the operator to point at the new batch.
Readings taken BEFORE the stop are still accepted. A Tilt collector may be part-way through a window and a bridge may be holding hours of backlog; those were genuinely measured while the batch was recording, and judging them by when they arrived would throw away real data for being late.
Stopping is idempotent — pressing it twice keeps the original moment rather than moving the cut-off forward — and reversible: Start recording appears in its place if you stopped the wrong batch, or when you drop the same device into the next batch.
Plans
Sensor webhooks work on every plan, including the free Cellar Hand tier. (The separate Sensors page under Cellar, for registering standing cellar devices, is limited to one on the free plan.)