Skip to content

fix(security): add HMAC signature to Process Engine outbound webhooks (#266) - #287

Merged
vybe merged 1 commit into
mainfrom
feature/266-webhook-hmac
Apr 10, 2026
Merged

fix(security): add HMAC signature to Process Engine outbound webhooks (#266)#287
vybe merged 1 commit into
mainfrom
feature/266-webhook-hmac

Conversation

@dolho

@dolho dolho commented Apr 8, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Add X-Trinity-Signature (HMAC-SHA256) and X-Trinity-Timestamp headers to all outbound webhook calls from the Process Engine
  • Signing key derived from SECRET_KEY via HMAC(SECRET_KEY, "webhook-signing") — no extra config needed
  • Payload serialized with sort_keys=True and compact separators for deterministic signatures

Changes

  • src/backend/services/process_engine/events/webhook_publisher.py — HMAC signing in _send_webhook(), new _compute_signature() static method
  • tests/unit/test_webhook_signature.py — 10 unit tests (determinism, sensitivity, header verification, receiver verification, serialization)

Receiver Verification

Receivers should verify signatures like this:

import hmac, hashlib, json, time

def verify(body: bytes, timestamp: str, signature: str, secret_key: str) -> bool:
    if abs(time.time() - int(timestamp)) > 300:  # 5-min replay window
        return False
    signing_key = hmac.new(secret_key.encode(), b"webhook-signing", hashlib.sha256).digest()
    expected = hmac.new(signing_key, f"{timestamp}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature.removeprefix("v1="), expected)

Test Plan

  • 10 unit tests passing: pytest tests/unit/test_webhook_signature.py -v
  • Manual: trigger a process with webhook configured, verify headers present

Closes #266

🤖 Generated with Claude Code

…ebhooks (#266)

Outbound webhook calls now include X-Trinity-Signature (v1=HMAC-SHA256)
and X-Trinity-Timestamp headers so receivers can verify Trinity as the
origin. Signing key derived from SECRET_KEY via HMAC("webhook-signing").
Payload serialized with sorted keys for deterministic signatures.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@dolho dolho changed the title fix(security): add HMAC signature to Process Engine outbound webhooks (#266) wip: fix(security): add HMAC signature to Process Engine outbound webhooks (#266) Apr 8, 2026
@dolho dolho changed the title wip: fix(security): add HMAC signature to Process Engine outbound webhooks (#266) fix(security): add HMAC signature to Process Engine outbound webhooks (#266) Apr 10, 2026
@dolho
dolho requested a review from vybe April 10, 2026 07:15
@vybe
vybe merged commit b9f0581 into main Apr 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Process Engine outbound webhooks lack HMAC signature verification

2 participants