#Webhooks

Webhooks POST a signed JSON message to your URL when something happens on your account. Add them in the panel under Webhooks (up to 10 per login), pick the events, and copy the secret used to sign deliveries. The Test button sends a webhook.test event.

#Events

A webhook with no events selected receives all of them. Reseller sub-users with their own webhooks receive rotation.completed and quota.exceeded for the proxies assigned to them.

#Delivery

POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: ProxyKite-Webhooks/1
X-Hyp-Event: rotation.completed
X-Hyp-Delivery: 5f0c6a1e-8a1b-4c55-9d1e-2b7f1c3d9a10
X-Hyp-Timestamp: 1791914400
X-Hyp-Signature: sha256=3b6f...e91c

{"id": "5f0c6a1e-8a1b-4c55-9d1e-2b7f1c3d9a10", "event": "rotation.completed", "created_at": "2026-10-09T18:00:00+00:00",
 "data": {"proxy_id": 7, "label": "Shop A", "port": 30007, "status": "ok", "ok": true, "old_ip": "1.2.3.4",
          "new_ip": "5.6.7.8", "method": "netmode", "duration_ms": 9000, "triggered_by": "api", "error": null}}

• One attempt, 5 second timeout, no retries, redirects not followed. Answer with any 2xx quickly and do the work afterwards. Anything else is logged as a failed delivery (visible in the panel).
• id (= X-Hyp-Delivery) is unique per delivery; use it to ignore duplicates.
• URLs must be public http(s) addresses — private, loopback and link-local targets are refused.

#Verifying the signature

X-Hyp-Signature is sha256= + hex HMAC-SHA256 of "<X-Hyp-Timestamp>.<raw request body>", keyed with the webhook's secret. Always verify against the raw body (before JSON parsing), compare in constant time, and reject old timestamps (we suggest 5 minutes).

import hashlib, hmac, os, time
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["HYP_WEBHOOK_SECRET"].encode()

@app.post("/hooks/hyp")
def hyp_webhook():
    ts = request.headers.get("X-Hyp-Timestamp", "")
    sig = request.headers.get("X-Hyp-Signature", "")
    body = request.get_data()  # raw bytes
    expected = "sha256=" + hmac.new(SECRET, ts.encode() + b"." + body, hashlib.sha256).hexdigest()
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300 or not hmac.compare_digest(expected, sig):
        abort(401)
    event = request.get_json()
    print(event["event"], event["data"])
    return "", 204

import crypto from 'node:crypto';
import express from 'express';

const app = express();
const SECRET = process.env.HYP_WEBHOOK_SECRET;

app.post('/hooks/hyp', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.get('X-Hyp-Timestamp') ?? '';
  const sig = req.get('X-Hyp-Signature') ?? '';
  const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(`${ts}.`).update(req.body).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  const ok = sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
  if (!fresh || !ok) return res.sendStatus(401);
  const event = JSON.parse(req.body.toString('utf8'));
  console.log(event.event, event.data);
  res.sendStatus(204);
});
app.listen(3000);

<?php
$secret = getenv('HYP_WEBHOOK_SECRET');
$body = file_get_contents('php://input');            // raw body
$ts = $_SERVER['HTTP_X_HYP_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_HYP_SIGNATURE'] ?? '';

$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, $secret);
if (! ctype_digit($ts) || abs(time() - (int) $ts) > 300 || ! hash_equals($expected, $sig)) {
    http_response_code(401);
    exit;
}
$event = json_decode($body, true);
error_log($event['event'] . ' ' . json_encode($event['data']));
http_response_code(204);

# Send yourself a correctly signed test delivery
SECRET='your-webhook-secret'
BODY='{"id":"test-1","event":"webhook.test","created_at":"2026-10-09T18:00:00+00:00","data":{"message":"hi"}}'
TS=$(date +%s)
SIG="sha256=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')
curl -X POST http://localhost:3000/hooks/hyp -H 'Content-Type: application/json' \
  -H "X-Hyp-Event: webhook.test" -H "X-Hyp-Timestamp: $TS" -H "X-Hyp-Signature: $SIG" -d "$BODY"

#Field notes

• rotation.completed → status is ok, failed or not_implemented; ok is true only for ok; error is set when it failed. triggered_by is where the rotation came from: api, link, panel, auto.
• quota.exceeded fires once when used_bytes reaches quota_bytes, and again only after the quota is reset or raised.