Signed webhooks

​

How it works

• A timestamp to prevent replay attacks
• A hash of the exact payload we sent

​

Headers

​

Signature scheme

X-Lettermint-Signature: t=1704067200,v1=5d41402abc4b2a76b9719d911017c592

• t = Unix timestamp (seconds) when signature was generated
• v1 = HMAC-SHA256 hex digest

​

Signed payload format

{timestamp}.{raw_json_body}

​

Computing the signature

const crypto = require('crypto')

const timestamp = '1704067200'
const rawBody = '{"id":"abc","event":"message.delivered",...}'
const secret = 'whsec_your_secret_here'

const signedPayload = `${timestamp}.${rawBody}`
const expectedSignature = crypto
  .createHmac('sha256', secret)
  .update(signedPayload)
  .digest('hex')

// expectedSignature should equal the v1 value from the header

​

Replay protection

1. Parse the t value from X-Lettermint-Signature
2. Compare with current time: |now - t| <= 300 seconds
3. Reject if outside the window

​

Implementation examples

const express = require('express')
const crypto = require('crypto')

const app = express()
const SECRET = process.env.LETTERMINT_WEBHOOK_SECRET

// Important: capture raw body for signature verification
app.use(express.json({
  verify: (req, res, buf) => {
    req.rawBody = buf
  }
}))

app.post('/webhooks/lettermint', (req, res) => {
  const signature = req.header('X-Lettermint-Signature') || ''
  const rawBody = req.rawBody

  // Verify signature
  if (!verifySignature(rawBody, signature, SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' })
  }

  // Signature valid - process event
  const event = req.body
  console.log('Verified event:', event.event, event.id)

  res.status(200).json({ ok: true })
})

function verifySignature(rawBody, signature, secret, tolerance = 300) {
  // Parse signature header: t=123,v1=abc...
  const elements = {}
  signature.split(',').forEach(element => {
    const [key, value] = element.split('=', 2)
    if (key && value) elements[key] = value
  })

  if (!elements.t || !elements.v1) {
    return false
  }

  const timestamp = parseInt(elements.t, 10)
  const providedSignature = elements.v1

  // Check timestamp freshness (replay protection)
  const now = Math.floor(Date.now() / 1000)
  if (Math.abs(now - timestamp) > tolerance) {
    console.warn('Timestamp too old or too new')
    return false
  }

  // Compute expected signature
  const signedPayload = `${timestamp}.${rawBody.toString()}`
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // Timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature),
    Buffer.from(providedSignature)
  )
}

app.listen(3000)

​

Step-by-step verification

1. Extract the signature header
   Copy

   const signature = req.headers['x-lettermint-signature']
   // Example: "t=1704067200,v1=5d41402abc4b2a76b9719d911017c592"
   

2. Parse timestamp and hash
   Copy

   const [tPart, v1Part] = signature.split(',')
   const timestamp = tPart.split('=')[1]  // "1704067200"
   const providedHash = v1Part.split('=')[1]  // "5d41402a..."
   

3. Check timestamp freshness
   Copy

   const now = Math.floor(Date.now() / 1000)
   if (Math.abs(now - parseInt(timestamp)) > 300) {
     throw new Error('Webhook timestamp too old')
   }
   

4. Get raw request body
   Copy

   // Must be the exact bytes received, not re-serialized JSON
   const rawBody = req.rawBody  // Buffer or string
   

5. Compute expected signature
   Copy

   const signedPayload = `${timestamp}.${rawBody}`
   const expectedHash = crypto
     .createHmac('sha256', secret)
     .update(signedPayload)
     .digest('hex')
   

6. Compare with timing-safe equality
   Copy

   const isValid = crypto.timingSafeEqual(
     Buffer.from(expectedHash),
     Buffer.from(providedHash)
   )
   

​

Finding your webhook secret

1. Navigate to Dashboard → Project → Routes → Select Route → Webhooks
2. Click on your webhook
3. Copy the secret (starts with whsec_)
4. Store it securely in your environment variables

​

Testing signature verification

​

Manual test with curl

# This will fail signature verification (as intended)
curl -X POST https://your-endpoint.com/webhooks/lettermint \
  -H "Content-Type: application/json" \
  -H "X-Lettermint-Signature: t=1704067200,v1=invalid" \
  -H "X-Lettermint-Event: webhook.test" \
  -d '{"id":"test","event":"webhook.test","data":{}}'

​

Using the dashboard

​

Production recommendations

​

Security

• Always verify signatures in production environments
• Use HTTPS endpoints - Lettermint only delivers to HTTPS URLs
• Rotate secrets periodically (e.g., every 90 days)
• Monitor failed deliveries in the dashboard for potential attacks

​

Performance

• Verify then queue - Return 200 immediately after verification, process async
• Set reasonable timeout - Your endpoint should respond within 30 seconds
• Implement idempotency - Use event.id to prevent processing duplicates

​

Error handling

• Return 401 for signature verification failures
• Return 200-299 for successful processing
• Return 500-599 for temporary errors (we’ll retry)

​

Troubleshooting

​

”Invalid signature” errors

• Verify you’re using the raw request body, not re-serialized JSON
• Check that your secret includes the whsec_ prefix
• Ensure body parsing middleware preserves raw body (see Express example)
• Confirm timestamp is being parsed as an integer, not string

​

Timestamp too old warnings

• Check your server’s system clock is synchronized (use NTP)
• Increase tolerance to 600 seconds (10 minutes) if clock drift is unavoidable
• Verify you’re parsing the t parameter correctly as Unix seconds

​

Works in test but fails in production

• Confirm production environment has correct LETTERMINT_WEBHOOK_SECRET
• Check production logging to see the actual signature format received
• Verify production isn’t modifying request body (compression, proxies, etc.)

​

Next steps

• Webhook events: See all available event types
• Introduction: Learn about webhook delivery and retries
• SDK documentation: Use our official SDKs with built-in verification