Public API keys and webhooks

Create scoped API keys for your TMS, payroll or BI tools, and receive signed webhook events at your own HTTPS endpoints.

For admins

The Developer pages let you connect EZ Logs to other systems. API keys let an integration call the EZ Logs Public API with only the permissions (scopes) you grant. Webhooks push events, such as a load status change or a submitted DVIR, to your own HTTPS endpoint as they happen. API reference documents every operation and event.

ELD records stay read-only: HOS logs (49 CFR 395 Subpart B) can never be created or edited through the API.

Before you start

• The Developer pages are part of the Public API feature. If you do not see Developer under Settings, the feature is not turned on for your account. Contact EZ Logs support to enable it.
• Data in other modules is only available when that module is on as well. For example, the loads operations need Dispatch, and pay statements need Driver pay.
• Owners and carrier admins can create, change and revoke keys and webhook endpoints. Support (read-only) users can view the pages but not change them. Drivers have no access. See Users and roles.
• Every change is recorded in the Audit log (without the key or secret itself).

Getting there

Open Settings in the left rail, then under Developer choose:

• API keys — manage keys.
• Webhooks — manage webhook endpoints and see their deliveries.
• API reference — the full Public API and webhook documentation.

The three pages are also linked by tabs at the top of each Developer page.

API keys

The API keys page lists each key with its name and prefix (for example ezl_live_Ab12Cd34…), scopes, status (Active, Expiring soon, Expired or Revoked), when and from which IP it was last used, its limits, its expiry and who created it. The full key is never shown again after it is created.

A carrier can have up to 25 active keys. Create a separate key for each integration so you can revoke one without affecting the others.

Keys start with ezl_live_ in production. Keys from a test environment start with ezl_test_ and do not work in production.

Create an API key

1. Go to Settings > Developer > API keys and click Create API key.
2. Enter a Name that identifies the integration (for example "McLeod TMS sync"), up to 100 characters.
3. Under Scopes, tick only what the integration needs (see the table below). Scopes cannot be changed later.
4. Optional: set Expires (optional) to a date after today. Leave it empty for a key that never expires.
5. Optional: change Rate limit (requests per minute). The default is 120; you can choose 1 to 1000.
6. Optional: enter an IP allow-list (optional): one IPv4 or IPv6 address or CIDR range per line (for example 203.0.113.0/24), up to 50 entries. Leave it empty to allow any IP.
7. Click Create key.
8. Copy the key from the dialog (use the copy button) and store it in your secret manager.
9. Tick I have stored it somewhere safe, then click Done.

Important: The key is shown only once. EZ Logs keeps only a hash of it and cannot show it again. If you lose it, rotate the key to get a new one.

Scopes

• Ticking loads:write also ticks loads:read.
• pay:read exposes driver earnings and deductions. Grant it only to your payroll integration.
• loads:write is the only write scope. Write requests are refused while your account is read-only for billing reasons (see Billing and your free trial).

Using a key

Send the key in the Authorization header of every request: Authorization: Bearer <key>. Portal sign-in sessions and cookies are not accepted by the Public API.

• Call GET /public/v1/me to check a new key: it returns the carrier, scopes, expiry and rate limit of the key and needs no scope.
• Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. When the per-minute limit is used up the API answers 429 rate_limited with a Retry-After header (seconds).
• Common errors: 401 invalid_api_key, 401 api_key_revoked, 401 api_key_expired, 403 ip_not_allowed (the caller is not on the IP allow-list), 403 feature_disabled (the Public API or the module is off), and 403 insufficient_scope (the key lacks the scope the operation needs).
• Lists return { data, nextCursor }; pass cursor=<nextCursor> for the next page (limit 1 to 200, default 50).

Edit a key

1. On API keys, click the pencil (Edit) next to an active key.
2. Change the Name, IP allow-list or Rate limit (requests per minute).
3. Click Save key.

Scopes and expiry cannot be edited. To change them, create a new key and revoke the old one.

Rotate a key

Rotate a key when it may have been exposed, or on a regular schedule.

1. Click Rotate next to the key.
2. Choose an Overlap: how long the old key keeps working so you can deploy the new one first. Options: None: stop the old one now, 1 hour, 24 hours (default), 3 days or 7 days.
3. Click Rotate key.
4. Copy the new key, tick I have stored it somewhere safe and click Done. The dialog shows until when the previous key keeps working.

The new key has the same scopes and limits as the old one.

Revoke a key

1. Click Revoke next to the key.
2. Confirm with Revoke key.

Requests with that key are refused immediately (401 api_key_revoked). Revoking cannot be undone.

Webhooks

EZ Logs sends each event as a signed JSON POST to your endpoint. A carrier can have up to 10 endpoints. Each endpoint card shows its URL and description, its status (Enabled, Enabled, failing, Disabled or Disabled after failures), the consecutive failure count against the auto-disable threshold, the last success and last failure, and the events it receives.

Events you can subscribe to

Alerts-based events need the matching alert rules (see Alerts and geofences), and module events need that module turned on.

Add an endpoint

1. Go to Settings > Developer > Webhooks and click Add endpoint.
2. Enter the Endpoint URL. It must start with https://, be on a public host, and must not contain a user name or password.
3. Optional: add a Description (optional), for example "TMS production".
4. Under Events, tick the events this endpoint should receive.
5. For pay events, first tick Include pay data (driver pay statements), then tick the pay event. Pay events are only sent to endpoints with this opt-in.
6. Click Add endpoint.
7. Copy the Signing secret, tick I have stored it somewhere safe and click Done. The secret is shown only once.

To change the URL, description or events later, click Edit on the endpoint card and then Save endpoint. Turning off Include pay data removes the pay events from the endpoint.

Send a test

Click Send test on the endpoint card. EZ Logs posts a signed webhook.test event and shows the result, for example "Test delivered: HTTP 200 in 120 ms" or "Test failed: HTTP 500".

Verify the signature

Every delivery has an EZL-Signature header in the form t=<unix seconds>,v1=<hex signature>. To verify it on your receiver:

1. Read t and the v1 value(s) from the header. During a secret rotation there are two v1 values (old and new secret): accept either.
2. Compute the HMAC-SHA256 (hex) of the string <t>.<raw body> using the endpoint's signing secret, over the raw request body exactly as received (before any JSON parsing).
3. Compare your result with each v1 value using a constant-time comparison.
4. Reject the request if t is more than 5 minutes away from your clock, to stop replays.

The API reference page has the same steps and a Node.js snippet you can copy.

Each delivery also carries EZL-Event-Id, EZL-Event-Type, EZL-Delivery-Id and EZL-Delivery-Attempt headers. The body is { id, type, apiVersion, createdAt, carrierId, data }.

Respond, retries and auto-disable

• Answer with any 2xx status within 10 seconds. Any other status, a redirect (redirects are not followed), a timeout or a connection error counts as a failed attempt.
• A failed delivery is retried with exponential backoff: after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours (7 attempts in total). After the last attempt the delivery is marked Failed.
• The event id is identical on retries and redeliveries. Use it to ignore duplicates.
• After 20 consecutive failed attempts the endpoint is disabled automatically (Disabled after failures), its pending retries are stopped and your admins get a portal notification. Any successful delivery resets the counter.

To bring a disabled endpoint back: fix your receiver, click Send test, then click Enable. Re-enabling resets the failure counter. You can also switch an endpoint off yourself with Disable.

Delivery log

1. Click Deliveries on an endpoint card.
2. Filter by Status (Succeeded, Failed, Retrying, Pending) or Event if needed. Click Load older deliveries to see more.
3. Click Details on a delivery to see the response code, latency, attempts, last attempt, next retry, the error, the request body and the first 512 characters of the response.
4. To send the same event again, click Redeliver (owners and carrier admins). The redelivery is a new delivery with the same event id and is marked Manual in the log.

Deliveries are kept for 30 days.

Rotate the signing secret

1. Click Rotate secret on the endpoint card.
2. Choose an Overlap (None: stop the old one now, 1 hour, 24 hours, 3 days or 7 days).
3. Click Rotate secret, then copy and store the new secret.

During the overlap every delivery is signed with both secrets (two v1 values), so you can update your receiver without missing events.

Delete an endpoint

Click Delete on the endpoint card and confirm with Delete endpoint. The endpoint stops receiving events and its delivery log is deleted. This cannot be undone.

API reference

Settings > Developer > API reference shows the full Public API: the base URL to use, every operation grouped by area with its parameters, required scope and response, the webhook events and their payloads, and the signature steps. Click Download the OpenAPI document (JSON) to import the API into your tools.

The API at /public/v1 only changes additively (new fields, operations and event types), so integrations should ignore fields they do not know. All timestamps are ISO-8601 UTC and distances are in miles.

Good practice

• Use one key per integration, with the fewest scopes and an IP allow-list where your integration has fixed addresses.
• Never put a key or signing secret in email, chat or source code. Keep them in a secret manager.
• Rotate keys and secrets with an overlap so the integration keeps working while you deploy the new value.
• Revoke keys you no longer use. Check Last used to find unused keys.