Webhooks

The signature verifier is a shipped SDK utility. The service that would send workflow webhooks remains on the preview horizon.

Preserve the raw body

const rawBody = await request.text()
const signature = request.headers.get('X-Nika-Signature') ?? ''

const valid = await Nika.verifyWebhook(
  rawBody,
  signature,
  process.env.NIKA_WEBHOOK_SECRET!,
)

The signed payload is <timestamp>.<raw body>. Verify before JSON parsing; parse and reserialization can change bytes.

Reject before dispatch

if (!valid) {
  return new Response('invalid signature', { status: 401 })
}

const event = JSON.parse(rawBody)
await dispatch(event)

The header shape is t=<unix timestamp>,v1=<hex signature>. The verifier:

refuses malformed fields;
refuses timestamps outside the tolerance;
computes HMAC-SHA256 with Web Crypto;
compares equal-length signatures in constant time.

Pass a fourth argument to change the default tolerance:

await Nika.verifyWebhook(rawBody, signature, secret, 60)

Test without a service

Build fixture signatures with Web Crypto in application tests. Keep replay tests for stale timestamps, modified bodies, wrong secrets and malformed headers.

Continue

Security boundary

Keep secrets and trust transitions explicit.

Remote errors

Decide how invalid delivery reaches product state.

Type index

Read the remote event and error shapes.

Source

Inspect the exact verifier.

Overview

Start

Project · live

Local API · live

Runtime · live

Remote API · preview

Operations

Reference

Preserve the raw body

Reject before dispatch

Test without a service

Continue

Security boundary

Remote errors

Type index

Source

​Preserve the raw body

​Reject before dispatch

​Test without a service

​Continue

Security boundary

Remote errors

Type index

Source

Preserve the raw body

Reject before dispatch

Test without a service

Continue