POST/api/v1/webhooks/dhcp/lease
Ingests a DHCP lease event from a Kea DHCP server.
A Kea DHCP server posts one lease event per request. The endpoint answers only after the event is committed, so a 202 means the event is durable, not merely received.
Authentication
HMAC-SHA256
Requests are signed, not authenticated with a bearer token.
- The sender computes the MAC over the timestamp and the raw request body joined by a period, and sends it with a key id so keys can be rotated.
- The signature is compared in constant time.
- The request timestamp must fall inside a freshness window. That check runs before the signature check.
- The tenant named in the event must match the tenant that the signing key belongs to.
Parameters
-
event idIdentifies the event. Storage is idempotent on the pair (tenant, event id).
Constraint Must be a UUID. Reuse the same id when you retry the same event.
Why A retried delivery is recorded once. That makes it safe for a sender to retry after a timeout without knowing whether the first attempt landed.
-
event timestampWhen the lease event happened.
Constraint Milliseconds. May not be in the future.
Why A future timestamp means a wrong clock on the sender, and accepting it would put events out of order in the lease history.
-
MAC addressHardware address of the leased host.
Constraint Any common formatting is accepted. It is canonicalised before storage.
Why Formatting differences (case, separators) would otherwise create duplicate hosts for one device.
-
tenantThe tenant the event belongs to.
Constraint Must match the tenant that the signing key belongs to.
Why The key is the authority. A sender holding one tenant's key cannot write events into another tenant.
Documented at beta access
Not published on this page.
- Names of the signature, timestamp and key id headers
- Encoding of the signature
- Freshness window duration
- Request body size cap
- Complete event schema beyond the fields above
Behavior
-
Freshness is checked before the signature
A request outside the freshness window is rejected before any MAC is computed.
Why A replayed request is turned away cheaply, so replay traffic cannot be used to burn compute on signature checks.
-
Constant-time comparison
The received signature is compared to the expected one in constant time.
Why A comparison that returns at the first differing byte leaks, through timing, how much of a forged signature was correct.
-
Identical 401 for every authentication failure
Every authentication failure returns the same 401 with no detail about which check failed.
Why Distinct errors for a bad key id, a stale timestamp and a bad MAC would let a caller probe each one separately.
-
Body size cap
The request body has a size cap. The value is documented at beta access.
-
Durable before acknowledged
The endpoint answers only after the event is committed to storage.
Why The sender can delete its copy once it sees a 202, because a 202 means the event is safe.
Responses
-
202Accepted. The event is committed.
What to do Treat the event as delivered.
-
202 (duplicate)Accepted with a duplicate indication: this event id was already stored for the tenant.
What to do Treat the event as delivered. Nothing was written twice.
-
409Conflict.
What to do Do not retry blindly. Check the event against what is already stored.
-
401Authentication failed. The body carries no detail, by design.
What to do Check the key id, the signing key, the timestamp and the signed bytes on your side.
-
503Storage is unavailable.
Header
Retry-AfterWhat to do Wait for the Retry-After interval, then retry with the same event id.
Retry guidance
-
On 503, honour Retry-After
Wait at least as long as the Retry-After header says before the next attempt.
-
On a network timeout, retry with the same event id
You cannot know whether the first attempt committed. Resend the identical event with the same event id.
Why Storage is idempotent on (tenant, event id), so if the first attempt landed, the retry is recorded as a duplicate and nothing is written twice.
Examples
signed_bytes = timestamp + "." + raw_request_body
mac = HMAC_SHA256(signing_key, signed_bytes)POST /api/v1/webhooks/dhcp/lease HTTP/1.1
Content-Type: application/json
<key id header>: <KEY_ID>
<timestamp header>: <TIMESTAMP>
<signature header>: <MAC>
{ "event_id": "<UUID>", "tenant": "<UUID>", "mac": "<MAC_ADDRESS>", "ts": <MILLISECONDS>, ... }