Skip to content

Webhooks

Jump to bottom
homelabforge edited this page Sep 25, 2026 · 2 revisions

Inbound Webhooks

Log fill-ups, odometer readings, and completed reminders from outside the UI: a shell script, Home Assistant, n8n, or anything else that can make an HTTP request.

This is the inbound direction. For sending data out to a dashboard, see Homepage Integration.

Setup

  1. Go to Settings → Integrations (admins only)
  2. Under Inbound Webhooks, enter a long random token in Webhook Ingest Token (for example the output of openssl rand -hex 32). It saves on its own. Leave it blank to switch ingest off.
  3. Keep a copy somewhere safe - it is the only credential these endpoints accept

Every request carries the token in the X-Webhook-Token header. It is deliberately not accepted as a query parameter, because query strings end up in proxy and browser logs. Requests are rate limited.

Endpoints

All paths are relative to your instance, e.g. https://mygarage.example.com/api/v1/webhooks/fuel.

POST /api/v1/webhooks/fuel

Logs a fill-up or a charge session. vin accepts either a VIN or a vehicle nickname.

{
  "vin": "1FTFW1ET5DFC10312",
  "date": "2026-08-24",
  "odometer_km": 143250,
  "liters": 62.4,
  "cost": 78.10,
  "is_full_tank": true
}

Both the odometer and the amount are optional, because a charge session can legitimately arrive with neither. For EVs, send kwh instead of liters, and optionally soc_start_pct, soc_end_pct, charge_level, charge_location, and battery_soh_pct.

POST /api/v1/webhooks/odometer

{ "vin": "1FTFW1ET5DFC10312", "odometer_km": 143250, "date": "2026-08-24" }

POST /api/v1/webhooks/reminders/complete

{ "vin": "1FTFW1ET5DFC10312", "reminder_id": 42 }

Values are sent in metric - kilometres, litres, kWh. MyGarage stores everything metric and converts for display, so neither the unit preference in your profile nor a vehicle's Odometer unit changes what these endpoints expect.

Telegram Fuel Commands

If you use the Telegram notification channel, you can log a fill-up by messaging the bot. Turn on Accept fuel commands under Settings → Notifications → Telegram (admins only). They are off while Enable Telegram notifications is off.

MyGarage fetches the bot's messages from Telegram itself, so it needs no public address and no webhook, only outbound access to api.telegram.org. It answers only the Chat ID set there. Any other chat is told which chat ID to set if you want to allow it.

/fuel <vin|nickname> <odometer>[km|mi] <volume>[L|gal|kWh] [price] [cost]

For example:

/fuel truck 143250mi 16.4gal 3.29
  • In a group, start with /fuel: the bot answers only commands there. In a private chat, fuel without the slash works too.
  • An odometer with no km or mi is in the vehicle's unit: its Odometer unit, or its owner's units when that is Account default. A volume with no unit is litres.
  • The fill-up is dated the day the message was sent, and counts as a full tank.
  • The reply repeats the numbers and units as MyGarage read them, so a misread is easy to spot. Send /help for the usage line.
  • A nickname with a space can't be used here. Use the VIN.

Units are part of the command, so imperial is fine here even though the REST endpoints are metric. There is no OCR and no free-text parsing - a command that does not match the shape above gets the usage line back.

Inbound commands are Telegram-only. The other notification channels are outbound and unaffected.

Troubleshooting

401 on every request Check the token is in the X-Webhook-Token header, not the URL, and matches Webhook Ingest Token in Settings → Integrations. A 503 means no token is set there.

"Vehicle not found" vin matches a full VIN or a nickname, ignoring case. Use the VIN if the nickname is longer than 17 characters or two vehicles share it. A nickname with a space needs quoting in a shell.

The reading logged but the dashboard looks stale A fuel webhook syncs the odometer log and clears cached analytics. An odometer webhook adds a reading to the odometer log. Reload the page; cached analytics refresh within 10 minutes.

Telegram fuel commands get no reply Check the status under Accept fuel commands: it should say Listening for commands. Another program is reading this bot's messages means something else is polling this bot or has set a webhook on it. Stop it, or give MyGarage its own bot.

See Also

Clone this wiki locally