Skip to content

Add configurable webhook HMAC secret#242

Open
allsanlawlas wants to merge 2 commits into
vsys-host:mainfrom
allsanlawlas:feature/separate-webhook-hmac-secret
Open

Add configurable webhook HMAC secret#242
allsanlawlas wants to merge 2 commits into
vsys-host:mainfrom
allsanlawlas:feature/separate-webhook-hmac-secret

Conversation

@allsanlawlas

@allsanlawlas allsanlawlas commented Jul 23, 2026

Copy link
Copy Markdown

Summary

Add an optional, dedicated webhook HMAC secret that can be generated and
activated from the payment gateway UI.

  • Store the dedicated secret in the existing global Setting table.
  • Sign confirmed invoice, unconfirmed invoice, and payout callbacks with the
    dedicated secret when configured.
  • Preserve API-key HMAC signing as the backward-compatible fallback.
  • Avoid exposing the API key as a callback header when the dedicated secret is
    active.
  • Add a two-step generate/copy/activate UI so generation cannot silently
    replace the active signing credential.
  • Document receiver configuration, activation, fallback behavior, rotation,
    and rollback considerations.

Motivation

Webhook HMAC signatures currently reuse the payment gateway API key. A
separate secret reduces coupling between API authentication and webhook
verification, avoids sending the API key to callback receivers in dedicated
mode, and makes webhook-secret rotation safer.

Compatibility and security behavior

  • Existing installations continue signing with the API key until a dedicated
    secret is explicitly activated.
  • The stored secret is never returned by the API.
  • Generated candidates are not persisted and responses are marked no-store.
  • The secret must be between 32 and 255 characters.
  • Callback signatures cover the exact compact JSON bytes sent over HTTP.
  • Invoice callbacks retain the legacy X-Shkeeper-Api-Key header only while
    API-key fallback is active.
  • Existing payout callback header behavior is preserved in fallback mode.
  • Removing the dedicated secret explicitly restores API-key fallback.
  • No schema migration is required because the existing settings table is used.

Validation

  • 61 passed on Python 3.11.
  • 61 passed on Python 3.13, matching the production Dockerfile runtime.
  • Callback coverage includes confirmed invoices, unconfirmed invoices, and
    payouts in dedicated-secret and API-key fallback modes.
  • API coverage includes authentication, validation, non-disclosure,
    generation, activation, replacement, and removal.
  • JavaScript syntax validation passed.
  • All 44 Jinja templates parsed successfully.
  • Alembic retains the single existing head e4f8a9b2c1d8.
  • Existing pre-feature SQLite database startup and settings persistence were
    smoke tested.
  • git diff --check passed.
HMAC_secret_active HMAC_secret_not_active

@allsanlawlas
allsanlawlas marked this pull request as ready for review July 23, 2026 21:07
@allsanlawlas
allsanlawlas marked this pull request as draft July 24, 2026 09:57
@allsanlawlas
allsanlawlas marked this pull request as ready for review July 25, 2026 07:36
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.

1 participant