Gareth Wilson Gareth Wilson

Guide to Bitculator Webhooks: Features and Best Practices

Published


Bitculator 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

FeatureDetails
ConfigurationData API v1: POST /api/v1/webhooks with a Bearer API key that has the data-api ability
Eventsalarm.triggered
EndpointsUp to 5 per account, HTTPS on public hosts only
Signaturehex HMAC-SHA256
Signature headerX-Bitculator-Signature: t=<unix seconds>,v1=<hex>
Signed content<t>.<raw body>
Event headerX-Bitculator-Event: alarm.triggered
BodyJSON, sent with POST
SecretPrefixed whsec_, shown only once when the endpoint is created
TestingPOST /api/v1/webhooks/{id}/test sends a signed test event
RetriesUp to 3 attempts per delivery with backoff. A test event is attempted once
Auto-disableAfter 10 consecutive failed deliveries
Delivery logGET /api/v1/webhooks/{id}/deliveries, kept for 30 days
Payload fields, timeout, source IPsNot 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 on the X-Bitculator-Event header can send each event type to its own destination.

The delivery log shows what happened to each attempt:

{
  "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 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:

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:

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

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.

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

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 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, and 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.

Acknowledge fast and process asynchronously

Verify, queue and return 200, then act in a worker. See why to process webhooks asynchronously.

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 verifies Bitculator deliveries and holds each alarm until your service has processed it.

Get started with Hookdeck for free and handle Bitculator webhooks reliably in minutes.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.