Webhooks

{
  "id": "d1f4...",                        // delivery id (X-Superkabe-Delivery-Id)
  "event": "mailbox.paused",              // event type
  "event_id": "e7c2...",                  // dedupe key (X-Superkabe-Event-Id)
  "organization_id": "org_8f1a...",       // your org
  "timestamp": "2026-04-29T14:22:18.412Z",// ISO-8601 emit time
  "data": { /* event-specific */ }
}

{
  "id": "d1f4a8e0-...",
  "event": "mailbox.paused",
  "event_id": "e7c2b3d4-...",
  "organization_id": "org_8f1a...",
  "timestamp": "2026-04-29T14:22:18.412Z",
  "data": {
    "mailbox_id": "mb_2k9...",
    "email": "outreach@acme-sales.com",
    "domain": "acme-sales.com",
    "reason": "bounce_rate_breached",
    "bounce_rate_24h": 0.087,
    "threshold": 0.05,
    "previous_state": "HEALTHY",
    "new_state": "PAUSED",
    "correlated_root_cause": "mailbox"
  }
}

{
  "id": "d4ab...",
  "event": "lead.health_changed",
  "event_id": "ec1a...",
  "organization_id": "org_8f1a...",
  "timestamp": "2026-04-29T14:23:01.118Z",
  "data": {
    "lead_id": "ld_91f...",
    "email": "jane@prospect.io",
    "previous_health": "GREEN",
    "new_health": "YELLOW",
    "score": 62,
    "reason": "domain_health_degraded"
  }
}

{
  "id": "d92c...",
  "event": "email.bounced",
  "event_id": "ee44...",
  "organization_id": "org_8f1a...",
  "timestamp": "2026-04-29T14:25:44.002Z",
  "data": {
    "send_id": "snd_7a2...",
    "lead_id": "ld_91f...",
    "campaign_id": "cmp_4b1...",
    "mailbox_id": "mb_2k9...",
    "bounce_type": "hard",
    "smtp_code": "550",
    "smtp_message": "5.1.1 The email account that you tried to reach does not exist"
  }
}

import crypto from 'crypto';
import express from 'express';

const app = express();
const SECRET = process.env.SUPERKABE_WEBHOOK_SECRET!; // whsec_...

// IMPORTANT: capture the raw body, not the parsed JSON.
app.post(
    '/webhooks/superkabe',
    express.raw({ type: 'application/json' }),
    (req, res) => {
        const header = req.header('X-Superkabe-Signature') || '';
        const parts = Object.fromEntries(
            header.split(',').map(p => p.split('='))
        ) as { t?: string; v1?: string };

        if (!parts.t || !parts.v1) return res.status(400).send('bad signature');

        const ageSec = Math.floor(Date.now() / 1000) - Number(parts.t);
        if (ageSec > 300) return res.status(400).send('signature too old');

        const signed = `${parts.t}.${req.body.toString('utf-8')}`;
        const expected = crypto.createHmac('sha256', SECRET).update(signed).digest('hex');

        const ok = crypto.timingSafeEqual(
            Buffer.from(expected, 'hex'),
            Buffer.from(parts.v1, 'hex')
        );
        if (!ok) return res.status(401).send('invalid signature');

        const event = JSON.parse(req.body.toString('utf-8'));
        // ... handle event.event, event.data ...
        res.status(200).send('ok');
    }
);

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

app = Flask(__name__)
SECRET = os.environ["SUPERKABE_WEBHOOK_SECRET"].encode()  # whsec_...

@app.post("/webhooks/superkabe")
def superkabe():
    header = request.headers.get("X-Superkabe-Signature", "")
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t, v1 = parts.get("t"), parts.get("v1")
    if not t or not v1:
        abort(400)

    if time.time() - int(t) > 300:
        abort(400)  # too old

    raw = request.get_data()  # raw bytes — do NOT use request.json
    signed = f"{t}.".encode() + raw
    expected = hmac.new(SECRET, signed, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(expected, v1):
        abort(401)

    event = request.get_json()
    # ... handle event["event"], event["data"] ...
    return "", 200

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "io"
    "net/http"
    "os"
    "strconv"
    "strings"
    "time"
)

var secret = []byte(os.Getenv("SUPERKABE_WEBHOOK_SECRET")) // whsec_...

func handler(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)

    var t, v1 string
    for _, part := range strings.Split(r.Header.Get("X-Superkabe-Signature"), ",") {
        kv := strings.SplitN(part, "=", 2)
        if len(kv) != 2 { continue }
        switch kv[0] {
        case "t": t = kv[1]
        case "v1": v1 = kv[1]
        }
    }
    if t == "" || v1 == "" {
        http.Error(w, "bad signature", 400); return
    }

    ts, _ := strconv.ParseInt(t, 10, 64)
    if time.Now().Unix()-ts > 300 {
        http.Error(w, "signature too old", 400); return
    }

    mac := hmac.New(sha256.New, secret)
    mac.Write([]byte(t + "."))
    mac.Write(body)
    expected := hex.EncodeToString(mac.Sum(nil))

    if !hmac.Equal([]byte(expected), []byte(v1)) {
        http.Error(w, "invalid signature", 401); return
    }
    // ... json.Unmarshal(body, &event); handle ...
    w.WriteHeader(200)
}