Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.barker.money/llms.txt

Use this file to discover all available pages before exploring further.

Barker uses webhooks for asynchronous, two-way communication.
  • Outbound — we POST events to your endpoint (engine deployed, fee accrued, etc.)
  • Inbound — your system POSTs events to us (user KYC update, off-chain reconciliation, etc.)
Both directions use the same HMAC-SHA256 signature scheme so you can reuse one signing helper.

​
Outbound (Barker → you)

​
Configure

In Portal → Webhooks:
  1. Add a destination URL (HTTPS only)
  2. Choose event types to subscribe
  3. Copy the outbound secret — shown once, used by you to verify signatures

​
Delivery guarantee

  • 3 attempts with exponential backoff: 30s → 120s → 600s
  • We consider 2xx as success; anything else triggers retry
  • After 3 failed attempts, status flips to failed. You can replay from the portal
  • Each delivery has a unique event_id — use it for idempotency on your side

​
Headers

Content-Type: application/json
X-Barker-Signature: <hex>          # HMAC-SHA256(outbound_secret, raw_body)
X-Barker-Event-Id:  <uuid>
X-Barker-Event-Type: engine.deployed

​
Verify (Node.js)

import crypto from "node:crypto";

export function verifyBarker(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

​
Verify (Python)

import hmac, hashlib

def verify_barker(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

​
Inbound (you → Barker)

Send events to us when something on your side affects a Barker user (KYC pass, off-chain settlement confirmed, etc.).

​
Endpoint

POST https://api.barker.money/api/partner/webhooks/inbound

​
Headers

Content-Type: application/json
X-Api-Key: bk_live_xxxxx
X-Barker-Signature: <hex>          # HMAC-SHA256(inbound_secret, raw_body)
X-Idempotency-Key: <your-unique-id>
The inbound secret is separate from the outbound one. Generate it in Portal → Webhooks — shown once.

​
Body

{
  "event_type": "partner.user.kyc_updated",
  "payload": {
    "external_user_id": "user_42",
    "kyc_status": "approved",
    "tier": 2
  }
}

​
Supported event types

event_typeWhen to send
partner.user.createdA user signed up on your side and is about to interact with a Barker engine
partner.user.kyc_updatedUser’s KYC tier changed
partner.reconciliation.confirmedOff-chain transfer reconciled (used for hybrid fiat → on-chain flows)

​
Response

StatusMeaningShould you retry?
200 receivedNew event recordedNo
200 duplicateSame idempotency_key already processedNo
400 unsupported_eventevent_type not in catalogNo (fix and resend)
401 invalid_signatureHMAC mismatchCheck secret; do not retry blindly
5xxOur problemYes, with backoff

​
Sign (Node.js)

import crypto from "node:crypto";

const body = JSON.stringify({ event_type, payload });
const signature = crypto
  .createHmac("sha256", process.env.BARKER_INBOUND_SECRET)
  .update(body)
  .digest("hex");

await fetch("https://api.barker.money/api/partner/webhooks/inbound", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": process.env.BARKER_API_KEY,
    "X-Barker-Signature": signature,
    "X-Idempotency-Key": crypto.randomUUID(),
  },
  body,
});

​
Replay protection

We dedupe by X-Idempotency-Key per partner. Sending the same key twice returns 200 duplicate without re-processing the payload — safe to retry on network errors.