Webhooks

​

Register an endpoint

curl --fail-with-body -X POST 'https://api.centaur.io/v2/webhooks' \
  -H "x-api-key: $CENTAUR_API_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "url": "https://example.com/centaur-webhooks",
    "description": "Production trade alerts",
    "eventTypes": ["feed_item.created", "feed_item.updated", "feed_item.deleted"],
    "filters": { "assetClasses": ["crypto"] }
  }'

​

Choose events and filters

​

Receive deliveries

1. Deduplicate on the event id. Delivery is at least once. A retry, a replay, or a recovered delivery repeats the same id.
2. Do not assume order. Deliveries run in parallel and failed ones retry later, so they can arrive out of sequence order. For feed items, current is the message’s state after the change.
3. Return a 2xx fast. Store the event, respond, then process it. An attempt fails if your status does not arrive within 10 seconds, including DNS lookup and connection, or if it is outside 2xx. Redirects are not followed, so a 3xx is a failure.
4. Verify the signature on the raw body, before you parse the JSON.

​

Verify signatures

1. Read t and every v1 from the header.
2. Reject the delivery when t is more than 5 minutes from your clock. This stops an old request from being replayed.
3. Compute the HMAC with each secret you hold. Accept the delivery when any v1 matches, using a constant-time comparison.

import { createHmac, timingSafeEqual } from 'node:crypto'

const TOLERANCE_SECONDS = 300

export function verifyCentaurSignature(header, rawBody, secrets, nowSeconds = Math.floor(Date.now() / 1000)) {
  let timestamp = null
  const signatures = []
  for (const part of header.split(',')) {
    const [key, value] = part.trim().split('=')
    if (key === 't') timestamp = Number(value)
    if (key === 'v1' && value) signatures.push(Buffer.from(value, 'hex'))
  }
  if (!Number.isInteger(timestamp) || Math.abs(nowSeconds - timestamp) > TOLERANCE_SECONDS) return false
  for (const secret of secrets) {
    const expected = createHmac('sha256', secret).update(`${timestamp}.`).update(rawBody).digest()
    for (const signature of signatures) {
      if (signature.length === expected.length && timingSafeEqual(signature, expected)) return true
    }
  }
  return false
}

import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300


def verify_centaur_signature(header, raw_body, secrets, now_seconds=None):
    now_seconds = int(time.time()) if now_seconds is None else now_seconds
    raw_body = raw_body.encode() if isinstance(raw_body, str) else raw_body
    timestamp, signatures = None, []
    for part in header.split(","):
        key, _, value = part.strip().partition("=")
        if key == "t" and value.isdigit():
            timestamp = int(value)
        elif key == "v1":
            signatures.append(value.encode())
    if timestamp is None or abs(now_seconds - timestamp) > TOLERANCE_SECONDS:
        return False
    for secret in secrets:
        expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest().encode()
        if any(hmac.compare_digest(expected, signature) for signature in signatures):
            return True
    return False

​

Test vectors

t=1759658400,v1=9d900da8b33831c814b94d20ac9baa0f1b532b0dbf7ebfb33b72b250a203c95a,v1=9ddbc989941745c3b41bf8003a840bed37c2a755e9a9af58f14eef7b6140e11e

printf '%s' '1759658400.{"id":"01a0e77a-0a10-79f4-94ae-460be7c2ff7f","type":"trade_event.created"}' \
  | openssl dgst -sha256 -hmac 'whsec_AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8'

​

Send a test delivery

​

Manage endpoints

• PENDING: waiting for its first or next attempt.
• IN_FLIGHT: being sent.
• SUCCEEDED
• HELD: kept unsent while the endpoint is paused or disabled.
• DEAD: every attempt failed. See Retries.

​

Retries and dead letters

​

Disabled endpoints

• it answers 410 Gone (410_gone). Use this status to tell Centaur to stop.
• at least 50 attempts in a row have failed and it has had no success for about two hours (sustained_failure). The two-hour clock restarts when you enable or resume the endpoint.
• its host starts resolving to an address Centaur refuses (unsafe_url).

​

Replay

curl --fail-with-body -X POST 'https://api.centaur.io/v2/webhooks/<endpoint-id>/replay' \
  -H "x-api-key: $CENTAUR_API_KEY" \
  -H 'content-type: application/json' \
  -d '{ "from": "2026-10-05T08:00:00.000Z" }'

• from selects deliveries created at or after that time, at most seven days ago. Older events are deleted, so reconcile beyond that with REST reads.
• fromSequence reaches only deliveries that were already attempted. Held deliveries that were never attempted have no sequence yet, so release them with from.
• Held deliveries in the range are released. Succeeded and dead deliveries are sent again as new deliveries with the same event id and a new sequence, so deduplicate on id. Deliveries already waiting or in flight are left alone.
• The endpoint must be active. Resume or enable it first.
• A replay that resends deliveries can run once a minute per endpoint. Otherwise the API returns 429 with Retry-After.

​

Limitations

• Detection is periodic. Centaur checks for trade and feed changes every 30 seconds and recalculates each positioning view at most every 1, 5, 10, or 15 minutes, depending on the view. Events arrive some time after the change.
• Only changes after registration. An endpoint receives changes detected after it was created. It can receive a trade_event.deleted, feed_item.updated, or feed_item.deleted for an item it never saw created.
• Corrections can reissue unchanged events under new IDs. When a trader’s history is corrected, Centaur deletes that trader’s later events and creates them again with new IDs, often with the same content. You receive trade_event.deleted and trade_event.created pairs with origin: replacement, and one feed_item.updated per affected message. Position IDs can change too, even on unchanged trades from later messages. origin: replacement is a same-message, same-pass hint, not a guaranteed correction label or an old-to-new ID map, so do not use it to track position identity. A pair with the same content is an ID change, not a new signal. One correction can send a burst as large as the trader’s history after the corrected time, and maxInFlight caps how many of those requests reach you at once. A very large correction can span several detection passes, so some re-created events carry origin: new and a message can get more than one feed_item.updated. To receive fewer events, subscribe to feed items only, where current shows that nothing changed.
• removed is not a reversal. An event in removed, or a trade_event.deleted, means stop treating that event as true. It does not mean the trader reversed the trade.
• Short-duration positions are delivered. /events, /feed, and /positions hide positions that lasted 60 seconds or less. Webhooks still deliver their events.
• No events for source edits or deletions. Source text is the version Centaur extracted the trade from: the original message, or its earliest edit when the original is unavailable. Later edits and deletions produce no event and do not remove extracted trades on their own.
• No events for visibility changes. When a trader becomes visible or hidden, or joins or leaves the feed’s editorial exclusions, existing items produce no events. Use a fresh REST read to reconcile.
• No history window for feed items. A late event on an older message produces a feed item event even when the message is outside the feed’s seven-day window.
• Prices can be missing. Trade prices may be null. A later price update does not send a follow-up trade webhook.
• Positioning depends on prices. Early Opportunities leaves out candidates without the prices it needs, so partial price failures can change membership and send alerts. Delivery does not hold back old rows or suppress those changes. Check the payload’s coverage and missingPriceGroups.