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-Signatureheader? - How do I handle the
alarm.triggeredevent 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_ 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
| Event | Description |
|---|---|
alarm.triggered | A 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
| Header | Description |
|---|---|
X-Bitculator-Signature | t=<unix seconds>,v1=<lowercase hex HMAC-SHA256> |
X-Bitculator-Event | The 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
- references/overview.md - Bitculator webhook concepts, the alarm.triggered event, what is and is not documented
- references/setup.md - Registering an endpoint with the Data API and storing the signing secret
- references/verification.md - Signature verification details and a standalone verifier