Webhooks

Truncus stuurt bezorgevenementen in realtime naar je endpoint.

Event-formaat

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

Events worden verstuurd als HTTPS POST-verzoeken met Content-Type: application/json.

Request-headers

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

Je endpoint moet antwoorden met HTTP 200. Niet-200-responses triggeren een retry.

Handtekening verifiëren

Alle webhook-verzoeken zijn ondertekend met HMAC-SHA256. Verifieer elk inkomend verzoek.

Handtekeningschema:

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

Node.js-verificatie:

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)
  )
}

Gebruik timingSafeEqual om timing-aanvallen te voorkomen. Wijs het verzoek af als de handtekening niet overeenkomt.

Replay-bescherming

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 te oud')
}

Volledig handler-voorbeeld

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()

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

  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('Ongeldige handtekening')
  }

  const event = JSON.parse(rawBody)

  if (event.status === 'bounced') {
    // bezorgingsrecord bijwerken
  }

  if (event.status === 'rejected') {
    // adres onderdrukken — niet opnieuw proberen
  }

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

Belangrijk: parsen als raw bytes

Parseer de request body als raw bytes vóór JSON-parsing. De handtekeningverificatie moet op de exacte ontvangen bytes plaatsvinden.

Retry-schema

Poging	Vertraging
1	Direct
2	1 minuut
3	5 minuten
4	15 minuten
5	1 uur
6	6 uur

Maximaal retry-venster: 24 uur. Events blijven onbeperkt herhaalbaar.

Handmatige replay

POST /v1/events/{event_id}/replay

Replay stuurt het opgeslagen event opnieuw. De e-mail wordt niet opnieuw verstuurd. Zie Replay →