KontyraKontyra Docs

Webhooks Laboratory & Delivery Engine

The definitive manual for Kontyra Webhooks: HMAC-SHA256 signature verification, instant URL ingestion, real-time Server-Sent Events (SSE), edit-and-replay testing, and guaranteed at-least-once delivery.

1. Overview & Event Architecture

The Kontyra Webhook system emits guaranteed real-time HTTP POST notifications whenever critical operations occur across DevOS, VUX, VyntaJobs, or Kontyra Console.

Reliable Webhook Delivery Pipeline

Guaranteed at-least-once delivery with cryptographic tampering prevention

Pipeline Flow
Ecosystem Event TriggerOrigin
Internal Event

A project is deployed, ticket scanned, or milestone funded inside a Kontyra microservice.

HMAC-SHA256 SignerCryptography
Tamper-Proof

Payload is hashed with your endpoint signing secret (whsec_...) and stamped with a UNIX timestamp.

Asynchronous Dispatch WorkerQueue & Worker
Exponential Retry

Dispatches HTTP POST to your webhook destination with automatic retry backoff on failures.

Laboratory Live StreamTelemetry
Realtime SSE

Delivery attempts, latency, and response bodies are streamed live to the dashboard via SSE.

2. Standard Event Catalog

Subscribe to specific topics in the Kontyra Console:

project.deployed

Emitted when a DevOS project build completes and edge subdomain goes live.

DevOS
attendee.checked_in

Emitted when a VUX ticket QR is scanned and validated at the event venue.

VUX
contract.milestone_funded

Emitted when an employer deposits funds into VyntaJobs escrow.

VyntaJobs
user.logout

Emitted when a user revokes their session from Kontyra Auth.

Auth

3. Cryptographic Signature Verification

Every webhook request includes the Kontyra-Signature header containing a timestamp and cryptographic HMAC digest:

Header Format
Kontyra-Signature: t=1790852000,v1=5257ab44e903de534d4ec3fa32454b5f9dddc8ac0ec1e5ee4fa037a398d50cc

To prevent replay attacks, compare the timestamp t against your current server time and verify that the request arrived within 5 minutes (300 seconds).

4. Implementation Snippets (Node / Python / Go)

Node.js / Express

verifyWebhook.js
import crypto from 'crypto';

export function verifyKontyraWebhook(rawBody, signatureHeader, secret) {
  const parts = signatureHeader.split(',');
  const timestamp = parts.find(p => p.startsWith('t='))?.replace('t=', '');
  const signature = parts.find(p => p.startsWith('v1='))?.replace('v1=', '');

  if (!timestamp || !signature) return false;

  // Protect against replay attacks (5 minute threshold)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp, 10)) > 300) return false;

  const payload = `${timestamp}.${rawBody}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Python (FastAPI / Flask)

verify_webhook.py
import hmac
import hashlib
import time

def verify_kontyra_webhook(raw_body: bytes, signature_header: str, secret: str) -> bool:
    try:
        parts = dict(item.split('=') for item in signature_header.split(','))
        timestamp = int(parts['t'])
        signature = parts['v1']

        # 5-minute replay tolerance
        if abs(time.time() - timestamp) > 300:
            return False

        payload = f"{timestamp}.".encode('utf-8') + raw_body
        expected = hmac.new(secret.encode('utf-8'), payload, hashlib.sha256).hexdigest()
        return hmac.compare_digest(signature, expected)
    except Exception:
        return False

5. Webhook Laboratory & SSE Live Streams

The Webhook Laboratory allows developers to create instant test endpoints at https://webhook.kontyra.name.ng/hooks/:token with zero server setup.

Listen to Live Webhook Stream
curl -N https://api.kontyra.name.ng/v1/webhooks/live?token=tok_demo_982b \
  -H "Accept: text/event-stream"

6. Edit-and-Replay Testing Engine

Debug webhook ingestion edge cases without waiting for live production events. Developers can select any historical payload, edit JSON fields in-browser, and re-dispatch with a freshly calculated HMAC signature to localhost tunnels (e.g. ngrok).

7. Exponential Backoff & Retry Matrix

If your server returns a non-2xx status code or times out (>10s), Kontyra automatically queues retries according to our exponential schedule:

AttemptDelay OffsetCumulative Time
Attempt 1Immediate0s
Attempt 21 minute+1m
Attempt 35 minutes+6m
Attempt 430 minutes+36m
Attempt 52 hours+2h 36m
Attempt 6 (Final)24 hours+26h 36m