Agent skill

Bitculator Webhooks Skill

Receive and verify Bitculator webhooks. Use when setting up Bitculator webhook handlers, debugging X-Bitculator-Signature verification, or handling the alarm.triggered price alarm event from the Bitculator crypto market data API.

Install this skill

npx skills add hookdeck/webhook-skills --skill bitculator-webhooks


When to Use This Skill

  • How do I receive Bitculator webhooks?
  • How do I verify the X-Bitculator-Signature header?
  • How do I handle the alarm.triggered event for a price alarm?
  • Why is my Bitculator webhook signature verification failing?
  • How do I register a Bitculator webhook endpoint and get its signing secret?

Essential Code (USE THIS)

Bitculator sends X-Bitculator-Signature: t=<unix seconds>,v1=<hex>. v1 is the lowercase hex HMAC-SHA256 of "<t>.<raw body>", keyed with the whole signing secret string's UTF-8 bytes: keep the whsec_ prefix and do not base64-decode it. Sign t exactly as it appears in the header, and use the raw body bytes, not re-serialised JSON. Bitculator has no verification SDK in its docs, so verify manually.

Accept the delivery if any v1= entry matches, and ignore other keys. A header with no t=, or a t= that is not all digits, fails. Compare hex case-insensitively: require exactly 64 hex characters, lowercase, then compare in constant time.

Verification (Node.js)

const crypto = require('crypto');

// rawBody: Buffer of the exact request bytes (express.raw({ type: '*/*' }), not express.json)
function verifyBitculator(rawBody, signatureHeader, secret, toleranceSeconds = 0) {
  if (!secret || !signatureHeader) return false;
  let t; const v1 = [];
  for (const kv of signatureHeader.split(',')) {
    const i = kv.indexOf('=');
    if (i <= 0) continue;
    const key = kv.slice(0, i).trim(), value = kv.slice(i + 1).trim();
    if (key === 't') t = value; else if (key === 'v1') v1.push(value);
  }
  if (!t || !/^[0-9]+$/.test(t)) return false;
  if (toleranceSeconds > 0 && !(Math.abs(Math.floor(Date.now() / 1000) - Number(t)) < toleranceSeconds)) return false;
  const expected = Buffer.from(crypto.createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex'));
  return v1.some((sig) => /^[0-9a-fA-F]{64}$/.test(sig) &&
    crypto.timingSafeEqual(Buffer.from(sig.toLowerCase()), expected));
}

Verification (Python)

import hashlib, hmac, re, time

def verify_bitculator(raw_body: bytes, header: str, secret: str, tolerance: int = 0) -> bool:
    if not secret or not header:
        return False
    t, v1 = None, []
    for kv in header.split(","):
        key, sep, value = kv.partition("=")
        if sep and key.strip() == "t": t = value.strip()
        elif sep and key.strip() == "v1": v1.append(value.strip())
    if not t or not re.fullmatch(r"[0-9]+", t):
        return False
    if tolerance > 0 and not abs(int(time.time()) - int(t)) < tolerance:
        return False
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest().encode()
    return any(re.fullmatch(r"[0-9a-fA-F]{64}", sig) and hmac.compare_digest(sig.lower().encode(), expected)
               for sig in v1)

Respond 401 when the header is missing or empty, malformed, or the signature does not match.

Timestamp window

The timestamp window is opt-in: BITCULATOR_WEBHOOK_TOLERANCE_SECONDS is unset or 0 by default (off). Bitculator's own PHP example accepts a delivery only when abs(time() - t) < 300, so set 300 to match it when Bitculator calls you directly (t is Unix seconds; the check uses the absolute difference). Behind Hookdeck leave it off: Hookdeck retries and replays resend the original headers and timestamp, and Hookdeck's own source verifies the signature without a tolerance, so a fixed window would reject legitimate redeliveries.

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Common Event Types

EventDescription
alarm.triggeredA price alarm fired. This is the only value Bitculator accepts in a webhook's events list

POST /api/v1/webhooks/{id}/test sends a signed alarm.triggered test event with test: true in the payload and real signature headers, so you can verify your receiver end to end.

Route on the X-Bitculator-Event header, after verifying. Bitculator names the event in X-Bitculator-Event: alarm.triggered. That header is not covered by the signature, so verify first and use it only as a routing label. The examples assume alarm.triggered when it is absent, and acknowledge (200) and skip any event they don't know.

The body is JSON, but its fields are not documented. The only documented body fact is test: true on test deliveries. The examples parse defensively (a non-JSON body is acknowledged and logged, not a 500), check every field's type before reading into it, and use an illustrative data.alarm shape in their tests. See references/overview.md.

Important Headers

HeaderDescription
X-Bitculator-Signaturet=<unix seconds>,v1=<lowercase hex HMAC-SHA256>
X-Bitculator-EventThe event name, alarm.triggered. Not signed: a routing label to read after verifying

Bitculator POSTs each event as JSON ("Bitculator POSTs each event as JSON with an HMAC signature header"), and The examples handle POST on /webhooks/bitculator and read the raw body with express.raw({ type: '*/*' }) (Next.js: request.arrayBuffer(); FastAPI: await request.body()) so the exact signed bytes are verified.

Delivery and Retries

Bitculator's docs: "Each delivery is attempted up to 3 times with backoff, a test event once; an endpoint auto-disables after 10 consecutive failed deliveries." Return a 2xx quickly, process asynchronously, and deduplicate, since a retried delivery repeats. The backoff intervals, timeout, source IPs and any delivery ID are not documented.

Environment Variables

BITCULATOR_WEBHOOK_SECRET=whsec_your_signing_secret   # returned once by POST /api/v1/webhooks; use as-is
BITCULATOR_WEBHOOK_TOLERANCE_SECONDS=0                # opt-in replay window; 300 matches Bitculator's example when called directly

Local Development

# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 bitculator --path /webhooks/bitculator

Reference Materials


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 17, 2026

View on GitHub →