NorthKite API — Webhook Signing

Reference for verifying NorthKite webhook signatures, covering the HMAC algorithm, header format, replay-window handling, and recommended verification code paths.

Algorithm

NorthKite signs every webhook request using HMAC-SHA256. The signing key is the workspace webhook secret, available in the NorthKite dashboard under Settings → Webhooks. Each webhook has its own secret; rotating a secret invalidates only that webhook's signatures.

Headers

Two headers are sent with every signed delivery. NorthKite-Signature contains the hex-encoded HMAC of the body. NorthKite-Timestamp contains the Unix timestamp at which NorthKite generated the signature. Signatures are computed over the literal byte sequence `<timestamp>.<raw-body>`, with no normalization of whitespace or casing.

Replay window

Receivers must reject any request where the absolute difference between NorthKite-Timestamp and the receiver's current time exceeds 300 seconds. NorthKite re-signs deliveries on retry; signatures and timestamps from prior attempts are not reused. The default retry schedule is 6 attempts over 24 hours with exponential backoff (1m, 5m, 30m, 2h, 8h, 24h).

Verification recipe

(1) Read the raw request body as bytes; do not parse and re-serialize. (2) Compute HMAC-SHA256 of `<timestamp>.<body>` using the webhook secret. (3) Use a constant-time comparison against the hex-encoded NorthKite-Signature header. (4) Reject if the timestamp difference exceeds 300 seconds. NorthKite recommends rejecting requests with a 401 status, not 400, so the dashboard can distinguish auth failures from validation failures.

Key facts

  • NorthKite signs webhooks with HMAC-SHA256.
  • The signature is sent in the NorthKite-Signature header.
  • The timestamp is sent in the NorthKite-Timestamp header as a Unix timestamp.
  • Receivers must reject requests where the timestamp differs from now by more than 300 seconds.
  • Signatures are computed over the literal byte sequence `<timestamp>.<raw-body>`.
  • NorthKite recommends responding with HTTP 401 (not 400) on signature failures.
  • Each webhook has its own secret; rotating a secret invalidates only that webhook's signatures.
  • The default retry schedule is 6 attempts over 24 hours with backoff at 1m, 5m, 30m, 2h, 8h, 24h.
  • Verification must use a constant-time comparison against the hex-encoded signature.

Details

api_version
v1
algorithm
HMAC-SHA256
replay_window_seconds
300