Webhook Signature Verification

Hopae Connect signs every outgoing webhook delivery with an HMAC-SHA256 signature so you can verify that requests genuinely come from Hopae and have not been tampered with in transit.

How signing works

Each delivery includes an X-Hopae-Signature header with two comma-separated fields:

X-Hopae-Signature: t=<unix-timestamp>,v1=<hex-hmac-sha256>

Field	Description
`t`	Unix timestamp (seconds) used in the signed payload
`v1`	Hex-encoded HMAC-SHA256 digest

The signed payload is constructed as:

<t>.<raw-request-body>

where <raw-request-body> is the exact UTF-8 bytes of the JSON body received in the HTTP request.

Verifying the signature

const crypto = require('crypto');

function verifyWebhookSignature(req, secret) {
  const sigHeader = req.headers['x-hopae-signature'];
  if (!sigHeader) {
    throw new Error('Missing X-Hopae-Signature header');
  }

  // Parse t= and v1= fields
  const parts = Object.fromEntries(
    sigHeader.split(',').map((p) => p.split('='))
  );
  const timestamp = parseInt(parts['t'], 10);
  const v1 = parts['v1'];

  if (!timestamp || !v1) {
    throw new Error('Malformed X-Hopae-Signature header');
  }

  // Replay protection: reject if timestamp is older than 5 minutes
  const nowSeconds = Math.floor(Date.now() / 1000);
  if (Math.abs(nowSeconds - timestamp) > 300) {
    throw new Error('Webhook timestamp too old — possible replay attack');
  }

  // Recompute signature using raw body bytes
  // IMPORTANT: use the raw body string, not re-serialised JSON
  const rawBody = typeof req.body === 'string' ? req.body : JSON.stringify(req.body);
  const toSign = `${timestamp}.${rawBody}`;
  const expected = crypto.createHmac('sha256', secret).update(toSign).digest('hex');

  // Constant-time comparison to prevent timing attacks
  const expectedBuf = Buffer.from(expected, 'hex');
  const receivedBuf = Buffer.from(v1, 'hex');
  if (expectedBuf.length !== receivedBuf.length || !crypto.timingSafeEqual(expectedBuf, receivedBuf)) {
    throw new Error('Signature mismatch — webhook not authenticated');
  }

  return true;
}

import hashlib
import hmac
import time

def verify_webhook_signature(headers: dict, raw_body: bytes, secret: str) -> bool:
    sig_header = headers.get('x-hopae-signature') or headers.get('X-Hopae-Signature')
    if not sig_header:
        raise ValueError('Missing X-Hopae-Signature header')

    parts = dict(p.split('=', 1) for p in sig_header.split(','))
    timestamp = int(parts.get('t', 0))
    v1 = parts.get('v1', '')

    # Replay protection: reject if older than 5 minutes
    if abs(time.time() - timestamp) > 300:
        raise ValueError('Webhook timestamp too old — possible replay attack')

    to_sign = f"{timestamp}.{raw_body.decode('utf-8')}"
    expected = hmac.new(secret.encode('utf-8'), to_sign.encode('utf-8'), hashlib.sha256).hexdigest()

    if not hmac.compare_digest(expected, v1):
        raise ValueError('Signature mismatch — webhook not authenticated')

    return True

Always use the raw request body bytes for signature verification. Do not parse the JSON and re-stringify it — serialisation order differences will cause the comparison to fail.

End-to-end Express example

Use express.raw() middleware on the webhook route so the handler receives the untouched body. Express’s default JSON parser destroys the exact bytes the signature was computed over.

const express = require('express');
const app = express();

// Your webhook secret, generated in the Console (app → webhook settings).
const WEBHOOK_SECRET = process.env.HOPAE_WEBHOOK_SECRET;

// Raw body is required for signature verification.
app.post(
  '/webhooks/hopae',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    try {
      verifyWebhookSignature(
        { headers: req.headers, body: req.body.toString('utf8') },
        WEBHOOK_SECRET,
      );
    } catch (err) {
      return res.status(401).json({ error: err.message });
    }

    const event = JSON.parse(req.body.toString('utf8'));
    // handle event.type — e.g. "verification.completed"
    console.log('Verified webhook:', event.eventId, event.event?.type);
    res.status(200).end();
  },
);

app.listen(3000);

Event types

Choose the event types in your app’s webhook settings in the Console. Each delivery includes the event type in the event field of the payload.

Event type	When it fires
`verification.created`	A new verification session has been created.
`verification.requested`	The integrator has initiated the verification flow.
`verification.workflow.started`	The workflow engine has begun executing nodes.
`verification.user.authentication_started`	The end-user has reached the identity provider.
`verification.user.authentication_succeeded`	The identity provider returned a successful authentication result.
`verification.user.authentication_failed`	The identity provider returned a failed authentication result.
`verification.completed`	The full verification succeeded end-to-end and claims are available via `/verifications/{id}/userinfo`.
`verification.failed`	The verification failed terminally (authentication failed, provider error, or workflow rejection).
`verification.workflow.cancelled`	The verification was cancelled by the integrator or the end-user.
`verification.session.timed_out`	The verification session exceeded its configured TTL without reaching a terminal state.

Each payload has the shape:

{
  "event": "verification.completed",
  "eventId": "evt_xxxx",
  "timestamp": "2026-04-09T00:00:00.000Z",
  "apiVersion": "v1",
  "clientId": "FK5b0KSM",
  "data": {
    "verificationId": "64f9dbca2375495aab49fd8cceeeabb2",
    "status": "completed",
    "providerId": "mitid",
    "workflowId": "wf_964850ee",
    "sessionExpiresAt": "2026-04-09T00:15:00.000Z",
    "event": {
      "type": "verification.completed",
      "timestamp": "2026-04-09T00:00:00.000Z",
      "metadata": {}
    },
    "result": {
      "loa": "3",
      "amr": ["pwd", "mfa"],
      "channel": { "type": "oidc", "transport": "redirect" }
    },
    "deviceType": "mobile",
    "countryCode": "DK",
    "countryName": "Denmark",
    "createdAt": "2026-04-09T00:00:00.000Z",
    "updatedAt": "2026-04-09T00:00:00.000Z"
  }
}

The top-level event is a string; the nested data.event is an object with its own type, timestamp, and optional metadata — they carry the same event type value, but data.event.metadata lets you pass extra context through the delivery pipeline.

Obtaining your webhook secret

Generate the webhook secret in the Console, in your app’s webhook settings. Store the secret securely (e.g. as an environment variable).

Replay protection

The t timestamp in the signature header reflects the moment the delivery was sent. Hopae recommends rejecting webhooks where |now - t| > 300 seconds (5 minutes) to prevent replay attacks, as shown in the examples above.

Backwards compatibility

Apps without a webhook secret deliver webhooks without an X-Hopae-Signature header. Generate the secret once in the Console to enable signing on your app.

Getting Started

Integrations

Concepts

Verifications

Data Types

Security

Webhook Signature Verification

How signing works

Verifying the signature

End-to-end Express example

Event types

Obtaining your webhook secret

Replay protection

Backwards compatibility

​How signing works

​Verifying the signature

​End-to-end Express example

​Event types

​Obtaining your webhook secret

​Replay protection

​Backwards compatibility

How signing works

Verifying the signature

End-to-end Express example

Event types

Obtaining your webhook secret

Replay protection

Backwards compatibility