Webhooks

Truncus delivers delivery events to your endpoint in real time.

Event shape

{
  "event": "email.delivery",
  "message_id": "msg_8f21",
  "status": "bounced",
  "reason": "mailbox_full",
  "timestamp": 1712345678
}

Events are sent as HTTPS POST requests with Content-Type: application/json.

Request headers

Content-Type: application/json
Truncus-Signature: tcsig_abcd1234
Truncus-Timestamp: 1712345678

Your endpoint must respond with HTTP 200 to acknowledge receipt. Non-200 responses trigger retry.

Verifying signatures

All webhook requests are signed with HMAC-SHA256. Verify every incoming request.

Signature scheme:

HMAC_SHA256(webhook_secret, timestamp + '.' + raw_body)

Node.js verification:

import crypto from 'crypto'

function verifyWebhookSignature(
  secret: string,
  timestamp: string,
  rawBody: string,
  signature: string
): boolean {
  const payload = `${timestamp}.${rawBody}`

  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex')

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

Use timingSafeEqual to prevent timing attacks. Reject the request if the signature does not match.

Replay protection

Reject requests with timestamps older than 5 minutes.

const now = Math.floor(Date.now() / 1000)
const ts = parseInt(req.headers['truncus-timestamp'], 10)

if (Math.abs(now - ts) > 300) {
  return res.status(400).send('Timestamp too old')
}

Complete handler example

import express from 'express'
import crypto from 'crypto'

const app = express()
app.use(express.raw({ type: 'application/json' }))

app.post('/webhooks/truncus', (req, res) => {
  const signature = req.headers['truncus-signature'] as string
  const timestamp = req.headers['truncus-timestamp'] as string
  const rawBody = req.body.toString()

  // Replay protection
  const now = Math.floor(Date.now() / 1000)
  if (Math.abs(now - parseInt(timestamp, 10)) > 300) {
    return res.status(400).send('Timestamp too old')
  }

  // Signature verification
  const payload = `${timestamp}.${rawBody}`
  const expected = crypto
    .createHmac('sha256', process.env.TRUNCUS_WEBHOOK_SECRET!)
    .update(payload, 'utf8')
    .digest('hex')

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature')
  }

  const event = JSON.parse(rawBody)

  if (event.status === 'bounced') {
    // update delivery record — event.reason has detail
  }

  if (event.status === 'rejected') {
    // suppress address — do not retry
  }

  res.status(200).send('ok')
})

Important: parse as raw bytes

Parse the request body as raw bytes before JSON parsing. Signature verification must run on the exact bytes received.

In Express: express.raw({ type: 'application/json' })

In Next.js Route Handler:

export async function POST(request: Request) {
  const rawBody = await request.text()
  const signature = request.headers.get('truncus-signature') ?? ''
  const timestamp = request.headers.get('truncus-timestamp') ?? ''
  // ... verify then parse JSON
}

Retry schedule

If your endpoint returns a non-200 response:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	15 minutes
5	1 hour
6	6 hours

Maximum retry window: 24 hours. Events remain replayable indefinitely.

Manual replay

If your endpoint was unavailable, replay events from the dashboard or API:

POST /v1/events/{event_id}/replay

Replay dispatches the stored event again. The email is not resent. See Replay →