Webhooks

Receive signed HTTP callbacks when transactions change state. Configure sandbox and production URLs separately on each application.

How to use

Set the webhook URL (and keep the signing secret) per environment on the application in Developers.
Expose an HTTPS endpoint that verifies X-Knos-Signature (HMAC-SHA256 of the raw body).
Deduplicate with X-Knos-Delivery-Id, then act on X-Knos-Event / the JSON payload.
Fire POST /webhooks/test (scope webhooks:manage) before going live.

Events

Event	When
`transaction.created`	Purchase accepted (pending money / awaiting fulfillment)
`transaction.processing`	Fulfillment in progress
`transaction.completed`	Success (funds settled)
`transaction.failed`	Terminal failure
`webhook.test`	From POST /webhooks/test

There is no separate transaction.pending event — use transaction.created. Reverse/refund webhooks are not emitted. Rotating the signing secret invalidates the previous secret immediately (zero grace). Retries reuse X-Knos-Delivery-Id; permanent HTTP 4xx responses are not retried (429/5xx/network are).

Headers

Delivery headers

X-Knos-Signature: <hex hmac-sha256 of raw body>X-Knos-Timestamp: <unix milliseconds>X-Knos-Delivery-Id: dlv_…X-Knos-Event: transaction.completed

Verify signature (Node)

JavaScript

import crypto from "node:crypto"; function verifyKnosSignature(rawBody, signatureHex, secret) {  const expected = crypto    .createHmac("sha256", secret)    .update(rawBody)    .digest("hex");  return crypto.timingSafeEqual(    Buffer.from(expected, "utf8"),    Buffer.from(signatureHex, "utf8"),  );}

Test delivery

Scope: webhooks:manage

POSThttps://confident-elephant-309.convex.site/v1/webhooks/test

Request

curl -sS -X POST https://confident-elephant-309.convex.site/v1/webhooks/test \  -H "Authorization: Bearer $KEY" \  -H "Content-Type: application/json" \  -d '{}'

200 when URL + secret configured

{  "ok": true}

Without a webhook URL: {"ok":false,"error":"Webhook URL or secret not configured"} (400). Retries use exponential backoff; Ops can retry failed deliveries from Office → Developers.

Also see Errors & status codes.