API and webhooks

Webhooks

A site administrator registers an endpoint URL and the event types it receives in GateRev (an empty list means all types). Each signing secret (whsec_…) is shown once — when the endpoint is created and when the secret is rotated. Every delivery is an HTTP POST with a JSON body.

Envelope (schemaVersion 1.0)

New fields may be added in a MINOR version; ignore fields you do not know. The shape of data depends on the event type.

Headers

Verifying the signature

Compute the HMAC over the raw body exactly as received — do not re-serialise the parsed JSON. Reject signatures older than 300 s.

import { createHmac, timingSafeEqual } from "node:crypto";
// header = X-GateRev-Signature; rawBody = the request body exactly as received (string)
const [t, v1] = header.split(",").map(p => p.slice(p.indexOf("=") + 1));
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
const ok = /^[0-9a-f]{64}$/.test(v1 ?? "")
  && timingSafeEqual(Buffer.from(expected), Buffer.from(v1))
  && Math.abs(Date.now()/1000 - Number(t)) <= 300; // replay window

Delivery and retries

• Success is any 2xx response within 10 s; anything else, including a network error, is retried.
• Retries after 1 min, 5 min, 30 min, 2 h, 12 h (each ±20 %), 6 attempts in total; then the delivery moves to the dead-letter list, where it is kept for 30 days and a site administrator can send it again.
• Redirects (3xx) are not followed and count as a failure — register the final https:// address. The endpoint must be a public https:// address.
• A retry sends the same body and the same id; use id to drop duplicates.

Event types (102)

• adapter.contract_rejected
• adapter.event_id_missing
• adapter.payload_too_large
• anpr.exit_held
• gate.denied
• anpr.exit_matched
• anpr.exit_seen
• anpr.insufficient_reads
• anpr.low_confidence
• anpr.manual_only
• anpr.match_ambiguous
• anpr.match_out_of_window
• anpr.plate_matched
• anpr.stale_read
• anpr.undated_read
• anpr.unknown_gate
• anpr.unknown_plate
• controller.barrier.position
• controller.curtain.broken
• controller.curtain.clear
• controller.heartbeat
• controller.presence.cleared
• controller.presence.detected
• controller.rejected
• controller.rate_limited
• controller.scale.reading
• controller.scale.cleared
• barrier.contact_stuck
• barrier.manual_open
• barrier.opened
• cert.expiring
• induction.passed
• person_cert.expiring
• dispatch.no_free_dock
• yard.task_advanced
• yard.chain_failed
• zone.driver_clear
• zone.person_detected
• zone.vap_trace
• zone.unload_finished
• zone.unload_started
• evac.drill_ended
• evac.drill_started
• evac.present
• notif.dead
• webhook.fanout_started
• webhook.ping
• webhook.paused_inactive
• evidence.verify_failed
• person.approved
• person.badge_revoked
• person.cancelled
• person.induction_completed
• person.off_site
• person.on_site
• person.registered
• person.rejected
• scale.error
• scale.invalid_reading
• scale.tare_anomaly
• scale.unstable
• scale.weight_recorded
• security.antipassback
• security.device_clock_skew
• security.device_rate_limited
• security.driver_document_refused
• security.pin_invalid
• security.pickup_code_invalid
• security.qr_replayed
• slot.booked
• slot.reassigned
• slot.released
• driver.document_replaced
• visit.approval_step
• visit.approved
• visit.arrived
• visit.at_scale
• visit.blocked
• visit.cancelled
• visit.called
• visit.condition_photo
• visit.document
• visit.departed
• visit.dock_arrived
• visit.dock_assigned
• visit.dock_finished
• visit.executor_revoked
• visit.driver_available
• visit.driver_unavailable
• visit.email_verified
• visit.entered_yard
• visit.exit_authorized
• visit.eta_delayed
• visit.no_show
• visit.override
• visit.rejected
• visit.slot_moved_by_driver
• visit.slot_proposal_decided
• visit.slot_proposed
• visit.submitted
• visit.unblocked
• visit.weighed

Carrier API

One key per carrier and organisation, issued by the site administrator and shown once. The key only sees and announces visits at that organisation's sites.

• Paths are relative to the address of your GateRev instance (the one your organisation signs in to), not to this website.
• Unknown fields in a request body are dropped without an error. A misspelt field (for example sealNo instead of sealNumber) is accepted and has no effect — check field names against the tables below.
• Versioning (current 1.0): a MINOR version may add optional request fields, response fields, reasonCodes and endpoints — ignore what you do not know and branch on the HTTP status for an unknown reasonCode. Removing or renaming a field, making an optional field required, or changing a type or a status code requires a new MAJOR version.

Authentication: Authorization: Bearer cr_… (pattern ^Bearer\s+(cr_[0-9a-f]{32})$).

Limits

• 60 requests per 5 min per key, all endpoints (429 too_many_requests). Counts every request with a valid key, in a sliding window.
• 30 announcement attempts per 1 day per key, POST /api/carrier/visits (429 carrier_quota). Counts attempts whose body passed validation, including ones then rejected (site, plate, blacklist, duplicate), in a sliding 24 h window; an Idempotency-Key replay is not counted.
• 60 assignment attempts per 1 day per key, PATCH /api/carrier/visits/{id} (429 assign_quota). Counts every attempt, including rejected ones (counted before the body is read), in a sliding 24 h window.
• Request body at most 64 KiB (413 payload_too_large).

Counters are kept in the memory of each server process: a restart resets them. Treat the limits as an approximate upper bound, not a guarantee.

Errors

Errors are application/problem+json; branch on reasonCode, not on title.

GET /api/carrier/visits

Visits of this carrier at the sites of the key's organisation, including visits it drives as a linked executor. Driver e-mail and phone are not returned.

Query parameters

Response 200

Errors

POST /api/carrier/visits

Announce a visit. The carrier is taken from the key, never from the body; driver and vehicle may be assigned later unless the site requires them at announcement.

Header Idempotency-Key (optional, ^[\x21-\x7e]{8,200}$): Same key and same body within 24 h return the first successful (201) response again, with replayed: true; same key with a different body returns 409. A rejected request (4xx, 429) does not hold the key — repeating it runs it again.

Request body (application/json)

Response 201

Errors

PATCH /api/carrier/visits/{id}

Assign or replace driver, vehicle or trailer on the carrier's own visit. Replacing the driver rotates the pass link; the old link stops working.

Request body (application/json)

Response 200

Errors

PUT /api/carrier/visits/{id}/eta

Report an absolute ETA from the carrier's TMS or telematics, optionally with a delay reason.

Request body (application/json)

Response 200

Errors

Schema files

Both files are generated from the code. webhook-envelope.schema.json (urn:gaterev:webhook:envelope:1) is a JSON Schema draft 2020-12 document for the webhook body. carrier-api.schema.json (urn:gaterev:carrier-api:1) is not itself a schema: it is a collection that lists, per endpoint, the method, path, errors and a JSON Schema draft 2020-12 for the query, request body and response. Ask us for the current files.