Vejledninger: Overvågning og webhooks

Overvågning og webhooks

Overvåg et køretøj, så giver Motorbay din server besked, når det ændrer sig. Efter hver ugentlig import får hvert køretøj, du overvåger, og som har ændret sig, ét signeret POST til dit endpoint, så du ikke selv skal slå hvert køretøj op igen.

Overvågning og webhooks kræver et betalt abonnement. Alle kald til dem er gratis: de tæller med i grænsen pr. minut, men ikke i abonnementet.

Sådan virker det

Registrer et https-endpoint med POST /v1/webhooks/endpoints. Gem signeringsnøglen fra svaret: den vises kun denne ene gang.
Overvåg køretøjer med PUT /v1/watches/vehicles/{vehicleId}.
Efter hver ugentlig import får hvert aktiveret endpoint ét POST pr. overvåget køretøj, der har ændret sig, med ugens ændringer.
Tjek signaturen på hver levering, før du stoler på den, og svar hurtigt med 2xx.

Registrer et endpoint

curl -X POST -H "X-Api-Key: $MOTORBAY_API_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/motorbay", "description": "Production"}' \
  "https://api.motorbay.app/v1/webhooks/endpoints"

json

{
  "endpoint": {
    "id": "12",
    "url": "https://example.com/motorbay",
    "description": "Production",
    "enabled": true,
    "disabledReason": null,
    "createdAt": "2026-11-02T09:15:00Z",
    "active": true
  },
  "secret": "whsec_KZhh+ceE0Bg1b5hNlewLsD/9F/k4bxEJD3yNJ1572UA="
}

Gem secret nu. Den kan ikke læses igen, kun skiftes.

URL'en skal være en hel https-URL på port 443, uden brugernavn, adgangskode eller fragment, og dens værtsnavn må kun pege på offentlige internetadresser. Alt andet giver 400 med koden WebhookUrlNotAllowed, og detail fortæller hvorfor.

Overvåg et køretøj

curl -X PUT -H "X-Api-Key: $MOTORBAY_API_KEY" \
  "https://api.motorbay.app/v1/watches/vehicles/9000000006320919"

Brug køretøjets id, det samme som i /v1/vehicles/{vehicleId}. Overvåger du allerede køretøjet, ændrer kaldet ingenting. Send DELETE til samme sti for at stoppe: leveringer, der allerede står i kø for køretøjet, trækkes tilbage og sendes ikke. GET /v1/watches/vehicles viser dine overvågede køretøjer efter køretøjs-id, med page og pageSize (højst 50) som i Sideinddeling. GET /v1/webhooks/endpoints viser dine endpoints, ældste først.

Overvågninger og endpoints hører til kontoen: alle kontoens nøgler ser og ændrer de samme.

Grænser

Abonnement	Overvågede køretøjer	Endpoints
Free	Ingen	Ingen
Starter	150	5
Pro	1.000	5
Enterprise og Business	5.000	5

På Free giver det 403 med koden PlanUpgradeRequired at overvåge et køretøj eller registrere et endpoint. Når du har nået dit abonnements antal, giver det 409 med WatchLimitReached eller EndpointLimitReached, og limit i svaret fortæller, hvor mange dit abonnement tillader. Et deaktiveret endpoint tæller med, til du sletter det.

Skifter du til et mindre abonnement, beholder du dine overvågninger og endpoints. De ældste, op til det nye abonnements antal, får stadig leveringer, og resten gør ikke. active på hver overvågning og hvert endpoint viser hvilke. Du kan altid læse og fjerne dem, så du kan rydde op.

Sådan ser en levering ud

http

POST /motorbay HTTP/1.1
Host: example.com
Content-Type: application/json
webhook-id: msg_8557c51855604cef95bdf88dad46cd4c
webhook-timestamp: 1793599230
webhook-signature: v1,NaxE3fBMR1BJkCYWJY4aqHW1tM/iCKRl2u7+Y1ye5P0=

{"type":"vehicle.changed","timestamp":"2026-11-02T06:00:00Z","data":{"vehicleId":"9000000006320919","observedOn":"2026-11-02","plates":[],"statuses":[{"status":"deregistered","changedOn":"2026-10-29","observedOn":"2026-11-02"}],"registrationStatuses":[],"inspections":[]}}

Eksemplet er signeret med nøglen ovenfor, så du kan teste dit tjek mod det.

type er vehicle.changed.
timestamp er, hvornår Motorstyrelsen offentliggjorde udtrækket, i UTC, så hvert forsøg sender den samme body. Headeren webhook-timestamp fortæller, hvornår dette forsøg blev sendt.
data.vehicleId er køretøjet. plates, statuses, registrationStatuses og inspections indeholder kun ugens ændringer, som de samme punkter som i /v1/vehicles/{vehicleId}/history.
webhook-id er den samme ved hvert forsøg på en levering. Du kan få en levering mere end én gang, så brug den til at springe en over, du allerede har behandlet.
User-Agent begynder med Motorbay-Webhooks/.

Hvad en ændring er

En levering er det, der har ændret sig mellem to ugentlige udtræk af Motorstyrelsens DMR-register, som vi har indlæst: en ny nummerplade, status, registreringsstatus eller syn. Den er ikke et levende billede af registret. Noget, der registreres i løbet af ugen, kommer efter næste udtræk og import, som regel inden for en uge, og et køretøj, der har ændret sig to gange på en uge, får én levering med sin tilstand ved udtrækket. Se Datakilde og aktualitet. Motorbay er ikke tilknyttet Motorstyrelsen.

Tjek signaturen

Leveringerne er signeret efter Standard Webhooks. Deres biblioteker til de fleste sprog tjekker dem for dig med din whsec_-nøgle.

Sådan tjekker du selv:

Tag det, der står efter whsec_ i din nøgle, og base64-afkod det. Det er nøglen.
Signer {webhook-id}.{webhook-timestamp}.{body} med HMAC-SHA256 og den nøgle. Brug bodyens præcise bytes, før du parser den.
Base64-kod resultatet. Leveringen er fra os, hvis det er lig med en af signaturerne i webhook-signature, efter v1, i hver. Der kan være flere, adskilt af mellemrum.
Sammenlign i konstant tid, og afvis en webhook-timestamp, der ligger mere end fem minutter fra dit ur.

I Node.js:

import crypto from "node:crypto";

function verify(secret, headers, rawBody) {
  const key = Buffer.from(secret.slice("whsec_".length), "base64");
  const signed = `${headers["webhook-id"]}.${headers["webhook-timestamp"]}.${rawBody}`;
  const expected = crypto.createHmac("sha256", key).update(signed).digest();
  const age = Math.abs(Date.now() / 1000 - Number(headers["webhook-timestamp"]));
  return age <= 300 && headers["webhook-signature"].split(" ").some((part) => {
    const given = Buffer.from(part.slice("v1,".length), "base64");
    return part.startsWith("v1,") && given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
}

Svar, nye forsøg og 410

Svar med 2xx inden for 15 sekunder, før langsomt arbejde: læg leveringen i kø, og behandl den bagefter.

Alt andet prøves igen: et 3xx (vi følger ikke omdirigeringer), alle 4xx undtagen 410, et 5xx, en timeout eller en afvist forbindelse. Nye forsøg sendes med samme webhook-id og body, efter 1 minut, 5 minutter, 30 minutter, 2 timer, 8 timer og 24 timer, hver ±10 %. Efter det syvende forsøg opgives leveringen. En Retry-After-header på dit svar kan få os til at vente længere, op til 24 timer, aldrig kortere.

Svar 410 Gone for at slå endpointet fra. Der sendes ikke mere til det, og GET /v1/webhooks/endpoints/{endpointId} viser "enabled": false og "disabledReason": "gone". Slet det, og registrer det igen for at starte forfra.

For hver levering gemmer vi det seneste forsøgs status og op til 1 KB af dit svar i 30 dage, så vi kan hjælpe, når en levering fejler.

Skift nøglen

curl -X POST -H "X-Api-Key: $MOTORBAY_API_KEY" \
  "https://api.motorbay.app/v1/webhooks/endpoints/12/rotate-secret"

Svaret indeholder den nye nøgle, som kun vises denne ene gang. I 24 timer signeres hver levering med både den nye og den gamle nøgle, så du kan skifte uden at miste en: godkend en levering, når en af dem passer.

Fejl

Status	Kode	Hvornår
400	`WebhookUrlNotAllowed`	URL'en kan ikke modtage leveringer. `detail` fortæller hvorfor
400	`ValidationFailed`	`url` mangler (`UrlRequired` i `errors`), eller `description` er over 200 tegn (`DescriptionTooLong`)
403	`PlanUpgradeRequired`	Overvågning og endpoints kræver et betalt abonnement
404	`VehicleNotFound`	Intet køretøj med det id, når du overvåger det
404	`WatchNotFound`	Du overvåger ikke det køretøj
404	`WebhookEndpointNotFound`	Du har intet endpoint med det id
409	`WatchLimitReached`	Du overvåger så mange køretøjer, som dit abonnement tillader
409	`EndpointLimitReached`	Du har så mange endpoints, som dit abonnement tillader
503	`ServiceUnavailable`	Vi kunne ikke bekræfte kontoens webhooks lige nu. Vent det antal sekunder, `Retry-After` angiver, og prøv igen

Se Fejl for, hvordan alle fejl ser ud.

Fandt du ikke svaret? Skriv til support@motorbay.app.