Skip to content

Notification authentication

Notification authentication ensures that receiving systems can verify that a webhook request actually originated from the system and that the payload was not modified during transmission.

Each webhook delivery is cryptographically signed so the receiving system can confirm:

  • the sender is authentic
  • the message has not been altered
  • the request is recent and not a replay

Authentication is defined separately from events and webhooks so the same configuration can be reused across multiple integrations.

Authentication method

Notifications currently use HMAC-SHA256 signing.

This method relies on a shared secret known by both:

  • the system sending the webhook
  • the system receiving the webhook

The secret is used to create a cryptographic signature for every notification payload.

Because the signature depends on the payload contents, any modification to the message would invalidate the signature.

Signing model

For every notification delivery the system generates a signing string with the following structure:

<timestamp>|<version>|<body>

This string is signed using:

HMAC-SHA256(shared_secret)

The resulting signature is included in the request headers sent with the webhook.

Typical headers include:

  • x-minyu-timestamp
  • x-minyu-version
  • x-minyu-signature

These headers allow the receiving system to validate the authenticity of the request.

Receiver verification

The receiving system should perform several checks before accepting the request.

Typical validation steps include:

  1. Verify the signature
    Recompute the HMAC using the shared secret and compare it with the x-minyu-signature header.

  2. Check timestamp freshness
    Reject requests that are older than a safe window (for example five minutes).

  3. Suppress duplicates
    Use the hook_id from the payload to avoid processing the same event more than once.

  4. Verify version compatibility
    Reject requests that reference unsupported payload versions.

Only if all validation checks succeed should the notification be processed.

Security purpose

Authentication protects webhook integrations by ensuring that:

  • only legitimate notifications are accepted
  • payloads cannot be modified without detection
  • replay attacks can be detected and rejected
  • duplicate events can be safely handled

Without authentication verification, external systems could receive forged or tampered notifications.

How-to

Related concepts