# 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)

```javascript
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)

```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/](https://github.com/hookdeck/webhook-skills/tree/main/skills/bitculator-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/bitculator-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/bitculator-webhooks/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](https://github.com/hookdeck/webhook-skills/blob/main/skills/bitculator-webhooks/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

```bash
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

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

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/bitculator-webhooks/references/overview.md) - Bitculator webhook concepts, the alarm.triggered event, what is and is not documented
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/bitculator-webhooks/references/setup.md) - Registering an endpoint with the Data API and storing the signing secret
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/bitculator-webhooks/references/verification.md) - Signature verification details and a standalone verifier