Skip to content

Webhooks

Jump to bottom
homelabforge edited this page Aug 24, 2026 · 1 revision

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
  2. Generate the webhook ingest token
  3. Copy it 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 the unit preference in your profile does not change what these endpoints expect.

Telegram Fuel Commands

If you already use the Telegram notification channel, you can log fuel by replying to the bot. Enable it under Settings → Integrations.

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

For example:

fuel truck 143250mi 16.4gal 3.29

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 or 403 on every request Check the token is in the X-Webhook-Token header, not the URL. Regenerate it in Settings → Integrations if you are unsure it is current.

"Vehicle not found" vin matches a full VIN or a nickname exactly. A nickname with a space needs quoting in a shell.

The reading logged but the dashboard looks stale Fuel and odometer webhooks sync the odometer log and clear cached dashboards. If it still looks wrong, reload the page.

See Also

Clone this wiki locally