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.
Guaranteed at-least-once delivery with cryptographic tampering prevention
A project is deployed, ticket scanned, or milestone funded inside a Kontyra microservice.
Payload is hashed with your endpoint signing secret (whsec_...) and stamped with a UNIX timestamp.
Dispatches HTTP POST to your webhook destination with automatic retry backoff on failures.
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:
Emitted when a DevOS project build completes and edge subdomain goes live.
Emitted when a VUX ticket QR is scanned and validated at the event venue.
Emitted when an employer deposits funds into VyntaJobs escrow.
Emitted when a user revokes their session from Kontyra Auth.
3. Cryptographic Signature Verification
Every webhook request includes the Kontyra-Signature header containing a timestamp and cryptographic HMAC digest:
Kontyra-Signature: t=1790852000,v1=5257ab44e903de534d4ec3fa32454b5f9dddc8ac0ec1e5ee4fa037a398d50ccTo 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
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)
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 False5. 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.
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:
| Attempt | Delay Offset | Cumulative Time |
|---|---|---|
| Attempt 1 | Immediate | 0s |
| Attempt 2 | 1 minute | +1m |
| Attempt 3 | 5 minutes | +6m |
| Attempt 4 | 30 minutes | +36m |
| Attempt 5 | 2 hours | +2h 36m |
| Attempt 6 (Final) | 24 hours | +26h 36m |