# Guide to Bitculator Webhooks: Features and Best Practices

[Bitculator](https://bitculator.com) provides crypto market data, such as prices, candles, sentiment and indicators, and lets you set price alarms. Its webhooks tell your service the moment an alarm fires, so a trading tool, bot or dashboard can react without polling the API.

This guide covers registering webhook endpoints through the Data API, verifying the `X-Bitculator-Signature` header, routing on `X-Bitculator-Event`, and coping with a short retry window and automatic disabling.

## What are Bitculator webhooks?

Bitculator webhooks are managed with its Data API v1. You register an HTTPS endpoint and the events it should receive, and Bitculator returns a signing secret. Bitculator then POSTs each event to the endpoint as JSON, signed with that secret, with the event name in an `X-Bitculator-Event` header.

There is one event, `alarm.triggered`, which fires when an alarm triggers. Alarms have a `notification` delivery channel: `email`, `push` or `webhook`.

## Bitculator webhook features

| Feature | Details |
| --- | --- |
| Configuration | Data API v1: `POST /api/v1/webhooks` with a Bearer API key that has the `data-api` ability |
| Events | `alarm.triggered` |
| Endpoints | Up to 5 per account, HTTPS on public hosts only |
| Signature | hex HMAC-SHA256 |
| Signature header | `X-Bitculator-Signature: t=<unix seconds>,v1=<hex>` |
| Signed content | `<t>.<raw body>` |
| Event header | `X-Bitculator-Event: alarm.triggered` |
| Body | JSON, sent with `POST` |
| Secret | Prefixed `whsec_`, shown only once when the endpoint is created |
| Testing | `POST /api/v1/webhooks/{id}/test` sends a signed test event |
| Retries | Up to 3 attempts per delivery with backoff. A test event is attempted once |
| Auto-disable | After 10 consecutive failed deliveries |
| Delivery log | `GET /api/v1/webhooks/{id}/deliveries`, kept for 30 days |
| Payload fields, timeout, source IPs | Not documented |

## Events and payloads

Each delivery names its event in the `X-Bitculator-Event` header, so route on that rather than on the body. The body is JSON, but Bitculator doesn't document its fields. A test event has `test` set to `true` in the payload, so you can tell tests from real alarms.

Behind Hookdeck, a [filter](/docs/filters) on the `X-Bitculator-Event` header can send each event type to its own destination.

The delivery log shows what happened to each attempt:

```json
{
  "data": [
    {
      "id": 311,
      "event": "alarm.triggered",
      "response_status": 200,
      "error": null,
      "attempts": 1,
      "delivered_at": "2026-07-02T21:14:09+00:00",
      "created_at": "2026-07-02T21:14:08+00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 6,
    "last_page": 1,
    "retention": "30 days"
  }
}

```

The `attempts` field counts tries, up to 3 per delivery. Send a test event to your endpoint early and build your parser from the body that arrives.

> **Inspect Bitculator webhooks as they arrive.** Register a [Hookdeck Inspect](https://inspect.hookdeck.com) URL as an endpoint and fire a test event to see the exact body and headers, with no account or setup required.

## Setting up Bitculator webhooks

Endpoints are managed through the Data API with a Bearer API key that has the `data-api` ability. Keep the key server-side. This request registers an endpoint for `alarm.triggered`:

```bash
curl -X POST "https://bitculator.com/api/v1/webhooks" \
  -H "Authorization: Bearer $BITCULATOR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"url": "https://example.com/webhooks/bitculator", "events": ["alarm.triggered"]}'

```

1. Run the request above with your HTTPS endpoint URL.
2. Copy `data.secret` from the response, prefix included, and store it as `BITCULATOR_WEBHOOK_SECRET`. It's only shown once, and listing endpoints never returns it.
3. Fire a test event with `POST /api/v1/webhooks/{id}/test`, using the `data.id` from the response.
4. Use `webhook` as the notification channel on the alarms that should reach your endpoint. The docs don't spell out how that channel maps to your endpoints, so trigger a test alarm and check the delivery log.

Bitculator's create-endpoint docs say a hostname that doesn't resolve, or resolves to a non-public address, fails without a retry. Check that your hostname resolves publicly before you register it.

If you lose the secret, delete the endpoint with `DELETE /api/v1/webhooks/{id}` and register it again. Deleting an endpoint abandons its pending deliveries.

To route through Hookdeck, create a source with the **Bitculator** type, paste the whole `whsec_` secret as the **Webhook Signing Secret**, and register the source URL as your endpoint. The source accepts `POST` only. For local development:

```bash
npx hookdeck-cli listen 3000 bitculator --path /webhooks/bitculator

```

## Securing Bitculator webhooks

`X-Bitculator-Signature` has the form `t=<unix seconds>,v1=<signature>`. The signature is the hex HMAC-SHA256 of the timestamp, a dot and the raw body, keyed with the whole secret. Use the secret exactly as Bitculator returned it, `whsec_` included. Don't strip the prefix or base64-decode the rest.

Bitculator's PHP example rejects a request when `t` is 300 seconds or more from the current time. The verifier below does the same by default. Hash the raw bytes you received, not re-serialised JSON.

The signature covers only `t` and the body, not `X-Bitculator-Event`. Verify the signature first, and treat the event header as a routing label, not as proof of anything.

### Node.js verification

```javascript
const crypto = require('node:crypto');

function verifyBitculatorSignature(rawBody, header, secret, toleranceSeconds = 300) {
  if (!Buffer.isBuffer(rawBody) || typeof header !== 'string' || typeof secret !== 'string' || !secret) {
    return false;
  }
  const parts = header.split(',').map((part) => part.trim());
  const times = parts.filter((part) => part.startsWith('t=')).map((part) => part.slice(2));
  if (times.length !== 1 || !/^[0-9]+$/.test(times[0])) return false;
  const timestamp = Number(times[0]);
  if (toleranceSeconds !== null && Math.abs(Date.now() / 1000 - timestamp) >= toleranceSeconds) {
    return false;
  }
  const message = Buffer.concat([Buffer.from(`${times[0]}.`, 'utf8'), rawBody]);
  const expected = crypto.createHmac('sha256', Buffer.from(secret, 'utf8')).update(message).digest();
  return parts
    .filter((part) => part.startsWith('v1='))
    .map((part) => part.slice(3))
    .some((candidate) => {
      if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
      const received = Buffer.from(candidate, 'hex');
      return received.length === expected.length && crypto.timingSafeEqual(received, expected);
    });
}

```

The handler verifies the request, acknowledges events it doesn't handle, and queues `alarm.triggered` deliveries with a hash of the raw body as a dedupe key. Parse and act on the alarm in the worker.

```javascript
const express = require('express');

const app = express();

app.post('/webhooks/bitculator', express.raw({ type: '*/*' }), async (req, res) => {
  const secret = process.env.BITCULATOR_WEBHOOK_SECRET;
  if (!secret) return res.sendStatus(500);
  if (!verifyBitculatorSignature(req.body, req.get('x-bitculator-signature'), secret)) {
    return res.sendStatus(401);
  }

  const event = req.get('x-bitculator-event');
  if (event !== 'alarm.triggered') return res.sendStatus(200); // acknowledge events you don't handle

  const dedupeKey = crypto.createHash('sha256').update(req.body).digest('hex');
  try {
    if (await alreadyHandled(dedupeKey)) return res.sendStatus(200);
    await queue.add('bitculator-alarm', { event, dedupeKey, body: req.body.toString('utf8') });
    await markHandled(dedupeKey);
  } catch {
    return res.sendStatus(503);
  }
  res.sendStatus(200);
});

```

`queue`, `alreadyHandled` and `markHandled` are placeholders for your queue and dedupe storage. Once you've seen a real delivery, switch the dedupe key to a field that identifies the alarm firing, if the body has one.

### Python verification

```python
import hashlib
import hmac
import re
import time

HEX_64 = re.compile(r"[0-9a-fA-F]{64}")
DIGITS = re.compile(r"[0-9]+")

def verify_bitculator_signature(raw_body: bytes, header, secret, tolerance_seconds=300) -> bool:
    if not isinstance(raw_body, bytes) or not header or not secret:
        return False
    parts = [part.strip() for part in header.split(",")]
    times = [part[2:] for part in parts if part.startswith("t=")]
    if len(times) != 1 or not DIGITS.fullmatch(times[0]):
        return False
    if tolerance_seconds is not None and abs(time.time() - int(times[0])) >= tolerance_seconds:
        return False
    message = times[0].encode("utf-8") + b"." + raw_body
    expected = hmac.new(secret.encode("utf-8"), message, hashlib.sha256).hexdigest()
    candidates = [part[3:] for part in parts if part.startswith("v1=")]
    return any(
        HEX_64.fullmatch(candidate) and hmac.compare_digest(candidate.lower(), expected)
        for candidate in candidates
    )

```

Hookdeck's Bitculator source checks the same signature with the secret you paste. It returns `200` to Bitculator either way and records any mismatch as failed verification, so those requests never reach your service. Hookdeck applies no window to `t` and forwards the original headers. If your service verifies the signature again behind Hookdeck, pass `null` (`None` in Python) as the tolerance, or a retry or replay that arrives later than 300 seconds will fail your check.

> **Make Bitculator webhooks production-ready.** [Hookdeck Event Gateway](/event-gateway) verifies every Bitculator delivery, stores it, and retries your service on a schedule you control, so a deploy or outage doesn't cost you an alarm.

## Bitculator webhook limitations and pain points

### Undocumented payload fields

**The Problem:** You can't write a typed parser for `alarm.triggered` from the docs alone.

**Why It Happens:** Bitculator says deliveries are JSON and names the event in `X-Bitculator-Event`, but it doesn't document the body's fields, beyond `test` on test events.

**Workarounds:**

* Fire a test event at a capture URL and record the body and headers.
* Verify against the raw bytes and parse defensively, ignoring fields you don't recognise.

**How Hookdeck Can Help:** Hookdeck stores every request with its full headers and body, so you can see the exact shape of each delivery and replay it against your handler while you build it.

### The secret is shown once

**The Problem:** A secret that wasn't saved, or that leaked, can't be retrieved from the API.

**Why It Happens:** Bitculator returns the secret only in the create response. Listing endpoints never includes it.

**Workarounds:**

* Save `data.secret` to your secret store in the same script that creates the endpoint.
* To replace a secret, register a new endpoint, switch your verifier to the new secret, then delete the old endpoint.

**How Hookdeck Can Help:** With Hookdeck in front, only the source holds the secret. Your service can trust Hookdeck's delivery instead of managing Bitculator secrets.

### Three attempts, then auto-disable

**The Problem:** A short outage loses alarms, and a longer one switches your endpoint off.

**Why It Happens:** Bitculator attempts each delivery up to 3 times with backoff, and only once for a test event. After 10 consecutive failed deliveries, the endpoint auto-disables. The docs don't give the backoff intervals or a timeout.

**Workarounds:**

* Respond quickly and process asynchronously.
* Poll `GET /api/v1/webhooks` and alert when `status` changes, `consecutive_failures` climbs or `disabled_at` is set.
* Check the delivery log for non-`2xx` `response_status` values.

**How Hookdeck Can Help:** Hookdeck answers Bitculator immediately, so deliveries succeed even while your service is down and failures don't count towards the disable threshold. It then gives your service its own [retries](/docs/retries), and [issues](/docs/issues) alert you when deliveries fail.

### A five-minute freshness check

**The Problem:** Following Bitculator's example, your receiver rejects requests whose timestamp is 300 seconds or more old, including late retries and replays.

**Why It Happens:** `t` is part of the signed content, and the example checks it against the current time.

**Workarounds:**

* Keep the check on requests that come straight from Bitculator, and keep your server clock in sync.
* Rely on deduplication rather than a tight window where late deliveries are expected.

**How Hookdeck Can Help:** Hookdeck verifies the signature without a time window, so a delivery that waited in Hookdeck's queue or was replayed later still reaches your service.

## Best practices

### Store the secret at creation

Write the create call and the secret storage as one step, and keep the API key and secret server-side only.

### Verify the raw body

The signature covers the exact bytes. Read the raw body before any JSON parser touches it.

### Make handlers idempotent

Each delivery can be attempted up to 3 times, and a repeat shouldn't act twice. Hash the raw body or use an ID from the alarm, and store the key before acting. See our [guide to webhook idempotency](/webhooks/guides/implement-webhook-idempotency).

### Acknowledge fast and process asynchronously

Verify, queue and return `200`, then act in a worker. See [why to process webhooks asynchronously](/webhooks/guides/why-implement-asynchronous-processing-webhooks).

## Conclusion

Bitculator sends `alarm.triggered` to HTTPS endpoints you register through the Data API, signed with `t=` and `v1=` in `X-Bitculator-Signature` and keyed by the whole `whsec_` secret. Save the secret when you create the endpoint, verify the raw body in constant time, route on `X-Bitculator-Event`, capture a test event to learn the body, and deduplicate because each delivery can be attempted up to 3 times.

[Hookdeck Event Gateway](https://hookdeck.com) verifies Bitculator deliveries and holds each alarm until your service has processed it.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle Bitculator webhooks reliably in minutes.