Skip to content

Notifications – Authentication

Authentication defines how Minyu cryptographically secures webhook deliveries to external systems.

Each webhook must reference one authentication configuration.

At present, Minyu supports:

  • HMAC-SHA256

Configuration

Authentication is configured from the Notifications interface.

Navigate to:

Data Exchange → Authentication

Creating an Authentication Configuration

Create a new authentication entry using the plus icon.

Each authentication configuration defines:

  • Authentication type
  • Shared secret

HMAC Authentication

When HMAC-SHA256 is selected:

  • Minyu generates a random secret key
  • The secret is stored encrypted
  • The full secret is shown once
  • Use the copy button to copy it immediately

This secret is later used to:

  • Sign every notification payload
  • Allow the receiving system to verify:
  • Sender authenticity
  • Payload integrity

Secret Security

The secret must be stored securely in the receiving system.
Anyone with access to the secret can forge webhook requests.

Save & Reuse

  • Authentication entries are inactive until saved
  • Once saved, an authentication entry can be:
  • Reused across multiple webhooks
  • Shared between classification and mutation notifications

How Signing Works

For each webhook delivery, Minyu:

  1. Creates a signing string:

<timestamp>|<version>|<body>

  1. Signs the string using:

HMAC-SHA256 + shared secret

  1. Sends the signature using headers:

  2. x-minyu-timestamp

  3. x-minyu-version
  4. x-minyu-signature

Receiver Validation Requirements

The receiving system must validate all of the following:

  1. Signature Match
    Recompute the HMAC using the shared secret and compare with x-minyu-signature.

  2. Timestamp Freshness
    Reject messages older than a safe window (for example 5 minutes).

  3. Duplicate Suppression
    Use hook_id from the payload to ignore already processed events.

  4. Version Handling
    Reject unknown x-minyu-version values.

Only if all checks pass should the message be accepted and processed.

Purpose

Authentication ensures that:

  • Only Minyu can send valid notifications
  • Webhook payloads cannot be tampered with
  • Replay attacks and duplicate processing are prevented