docs / integrations

Webhooks

Receive signals in your own service with signed HTTP callbacks.

Register an endpoint

Add a webhook URL in your account. RELAY sends a POST for every signal routed to the webhook destination, with a signature header you should verify.

Verify the signature

import crypto from 'node:crypto'

export async function POST(req: Request) {
  const body = await req.text()
  const sig = req.headers.get('x-knar-signature') ?? ''
  const expected = crypto
    .createHmac('sha256', process.env.KNAR_WEBHOOK_SECRET!)
    .update(body)
    .digest('hex')

  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return new Response('invalid signature', { status: 401 })
  }

  const signal = JSON.parse(body)
  // handle signal.agent, signal.token, signal.score ...
  return new Response('ok')
}

Retries

Non-2xx responses are retried with exponential backoff for up to 24 hours. Every delivery carries an idempotency key in x-knar-delivery.