SupportWire Docs

Identity & HMAC

Securely identify logged-in users to the widget with an HMAC signature.

Open in ChatGPT Open in Claude

HMAC signature generator

Compute a userSignature to test your integration. Everything runs locally — your secret never leaves the browser.

userSignature
—

HMAC-SHA256 of the lowercased, trimmed identity, hex-encoded — the same recipe as the server examples below.

Anonymous visitors work with no setup. To attach conversations to a known user — and prevent anyone from impersonating them — identify the user and sign the identity value with HMAC.

Identity values

Pass one identity key:

  • userEmail — the user's email, or
  • userExternalUserId — your own stable user id (wins if both are set).
new SupportWireWidget({
  widgetSlug: 'YOUR_WIDGET_SLUG',
  userEmail: '[email protected]',
});

This is enough to identify the user, but unsigned — only use it for low-trust contexts. For production, add an HMAC signature.

HMAC verification

Find your widget secret in Settings → Widgets. Compute an HMAC-SHA256 of the identity value (the same email or external id you pass to the widget), hex-encoded, and pass it as userSignature.

Warning — Compute the signature on your server. Never ship the widget secret to the browser.

Server (Node.js)

import crypto from 'node:crypto';
 
function widgetSignature(identity, secret) {
  return crypto
    .createHmac('sha256', secret)
    .update(identity.trim().toLowerCase())
    .digest('hex');
}
 
const userSignature = widgetSignature('[email protected]', process.env.WIDGET_SECRET);

Send userSignature to the page and pass it through:

new SupportWireWidget({
  widgetSlug: 'YOUR_WIDGET_SLUG',
  userEmail: '[email protected]',
  userSignature, // from your server
});

Server (Elixir)

identity = String.downcase(String.trim(email))
 
signature =
  :crypto.mac(:hmac, :sha256, secret, identity)
  |> Base.encode16(case: :lower)

Server (Ruby)

require "openssl"
 
identity = email.strip.downcase
signature = OpenSSL::HMAC.hexdigest("SHA256", secret, identity)

Custom attributes

Attach extra data to the contact via userData:

new SupportWireWidget({
  widgetSlug: 'YOUR_WIDGET_SLUG',
  userEmail: '[email protected]',
  userSignature,
  userData: {
    name: 'Alice Johnson',
    plan: 'Pro',
    account_created_at: 1640995200,
  },
});

Attributes show up on the contact in the admin dashboard.