Webhooks

Target notification signing contract

This proposed profile uses HMAC-SHA256 with an out-of-band shared key. It is a design choice to agree with the receiver, not a claim about a deployed service.

Target webhook profile v1 — not a deployed endpoint guarantee
Content-Type: application/json; charset=utf-8
X-LTANS-Key-ID: key-test-001
X-LTANS-Timestamp: 1792040400
X-LTANS-Event-ID: evt-test-001
X-LTANS-Signature: v1=<lowercase hex HMAC-SHA256>
signedBytes = UTF8(timestamp + "." + eventId + ".") || rawBody
secret = BASE64_DECODE(secretFromSecureProvisioning)
Rules: exact raw bytes; reject unknown key; constant-time MAC comparison;
abs(receivedUnixSeconds - signedTimestamp) <= 300 (target test profile);
require header eventId == parsed body.eventId; deduplicate per tenant + eventId;
persist inbox before acknowledging; retain event IDs through the agreed replay window.
Rotation: provision new key securely, overlap by keyId for an agreed interval, retire old key.
Never place the shared secret in a browser bundle or logs.

Delivery and recovery

• Require HTTPS, bound payload size, reject unauthorized internal targets and apply SSRF-aware DNS checks.
• The receiver durably commits its inbox before 2xx and deduplicates by tenant and eventId.
• Use bounded backoff; attempts, schedule and retention are environment-agreed.
• Ordering is per aggregate partition; check state revisions and re-query when events arrive late.
• Authorized replay retains eventId and does not duplicate metering.

Endpoint lifecycle and persistent failures

01

Register

Register allowlisted HTTPS; the backend resolves and checks destinations under SSRF policy.

02

Verify

Check receiver authority and message verification; use a challenge only if the profile defines one.

03

Deliver

Retain attempts, HTTP outcomes and retry schedule; the receiver commits its inbox before success.

04

Recover

Persistent failures trigger policy-based review/pause; authorized replay retains IDs and reconciles state.

Signing keys rotate by keyId over secure provisioning. Removal uses the existing DELETE operation; other administrative actions without dedicated endpoints remain explicitly scoped.

Next steps