Webhooks

​

Delivery headers

​

Verify before you parse

1. Read the raw request body as bytes. Do not re-serialize parsed JSON: key order and whitespace would differ and the signature would never match.
2. Recompute HMAC-SHA256(secret, f"{timestamp}.".encode() + raw_body) using the timestamp header value.
3. Compare the recomputed sha256=<hex> string to the X-Enoki-Signature header in constant time (hmac.compare_digest). Never use == on the digest.
4. Reject the delivery if the signed timestamp is outside a freshness window (we recommend 5 minutes). This bounds replay of a captured request.

import hashlib
import hmac
import os
import time
from datetime import datetime, timezone

# Load the shared signing secret from your environment / secrets manager.
HMAC_KEY = os.environ["ENOKI_WEBHOOK_KEY"].encode()
FRESHNESS_WINDOW_SECONDS = 300  # reject deliveries older than 5 minutes

def verify(raw_body: bytes, signature_header: str, timestamp_header: str) -> bool:
    try:
        # 1. Reject stale / replayed deliveries using the signed timestamp.
        signed_at = datetime.strptime(timestamp_header, "%Y-%m-%dT%H:%M:%SZ")
        signed_at = signed_at.replace(tzinfo=timezone.utc)
        age = abs(time.time() - signed_at.timestamp())
        if age > FRESHNESS_WINDOW_SECONDS:
            return False

        # 2. Recompute the HMAC over the EXACT raw bytes + the signed timestamp.
        signed_payload = f"{timestamp_header}.".encode() + raw_body
        expected = "sha256=" + hmac.new(HMAC_KEY, signed_payload, hashlib.sha256).hexdigest()

        # 3. Constant-time compare. Never `==` on the digest.
        return hmac.compare_digest(expected, signature_header)
    except (ValueError, TypeError):
        # Malformed timestamp or signature header: unverified, not an error.
        # Without this, garbage headers would raise (strptime / compare_digest)
        # and turn into 500s in your receiver.
        return False

​

Delivery payload

​

Good to know

• Retries mean possible duplicates. Failed deliveries (network errors, 5xx responses) are retried with backoff, so your receiver may see the same event more than once. Deduplicate on assessment_run_id plus event if that matters to you.
• Respond with a 2xx quickly. Any 2xx counts as delivered. A 4xx is treated as a permanent rejection and is not retried.
• Deliveries never follow redirects. Point the destination URL directly at your receiver.
• HTTPS only. Plain-HTTP destination URLs are rejected when you configure the webhook, and URLs resolving to private or internal addresses are rejected before every delivery.
• Slack destinations are not signed. This recipe applies to the generic webhook only; Slack incoming-webhook deliveries carry no signature headers.
• Use the send-test action in workspace settings to fire a sample delivery at your receiver while you build the verifier.