Skip to main content
If you receive webhooks from Fluxomail (or plan to for specialized integrations), verify each request using an HMAC signature header. Signature
  • Header: fluxomail-signature (or X-Fluxomail-Signature)
  • Algorithm: HMAC‑SHA256 with your shared secret
  • Format: sha256=<hex> or raw <hex> digest
SDK helper (Node)
import { webhooks } from '@fluxomail/sdk'

// rawBody: exact request body as a string (do not JSON.parse before verifying)
const ok = webhooks.verifyHmacSignature(rawBody, req.headers, { secret: process.env.FLUXOMAIL_WEBHOOK_SECRET! })
if (!ok) return res.status(401).end('invalid signature')

const out = webhooks.verifyAndParse(rawBody, req.headers, { secret: process.env.FLUXOMAIL_WEBHOOK_SECRET! })
if (!out.ok) return res.status(401).end('invalid signature')
for (const evt of out.events) {
  // handle event (evt.id, evt.type, evt.data)
}
Express example (raw body)
import express from 'express'
import bodyParser from 'body-parser'
import { webhooks } from '@fluxomail/sdk'

const app = express()
app.post('/webhooks/fluxomail', bodyParser.text({ type: '*/*' }), (req, res) => {
  const raw = req.body as string
  const ok = webhooks.verifyHmacSignature(raw, req.headers as any, { secret: process.env.FLUXOMAIL_WEBHOOK_SECRET! })
  if (!ok) return res.status(401).end('invalid signature')
  const out = webhooks.verifyAndParse(raw, req.headers as any, { secret: process.env.FLUXOMAIL_WEBHOOK_SECRET! })
  if (!out.ok) return res.status(401).end('invalid signature')
  // process out.events
  return res.status(200).end('ok')
})
Next.js App Router example
// app/api/fluxomail/webhook/route.ts
import { webhooks } from '@fluxomail/sdk'

export const runtime = 'nodejs'
export async function POST(request: Request) {
  const raw = await request.text()
  const ok = webhooks.verifyHmacSignature(raw, request.headers, { secret: process.env.FLUXOMAIL_WEBHOOK_SECRET! })
  if (!ok) return new Response('invalid signature', { status: 401 })
  const out = webhooks.verifyAndParse(raw, request.headers, { secret: process.env.FLUXOMAIL_WEBHOOK_SECRET! })
  if (!out.ok) return new Response('invalid signature', { status: 401 })
  // process out.events
  return new Response('ok', { status: 200 })
}
Payloads
  • Single event: { id, type, created, data }
  • Batched array: [ { id, type, created, data }, ... ]
  • Envelope { events: [...] } is also supported by the parser
Tips
  • Always verify before parsing JSON.
  • Keep secrets on the server; never expose them to browsers or client apps.
  • Handle retries idempotently (events include a stable id).
See also: SDKs & Clients