Skip to main content
Barker delivers product events to your endpoint as POST requests with a JSON body and an HMAC-SHA256 signature. Subscribe and inspect delivery logs in Portal → Webhooks.

Event types

Two categories — lifecycle events fire when a chain log appears at confirmation depth (one event per log), operational events fire from the daily metrics processor (one per product per day at most). We add new event types over time. Treat unknown event_type values as a no-op — don’t reject them.

Lifecycle events (tx-driven)

Payload (deposit.confirmed / redeem.confirmed):
Payload (redeem.requested — async vaults only):
See Deposit/Redeem Lifecycle for the full state diagram, sync vs async sequencing, and how to reconcile with the /position endpoint.

Operational events (daily aggregate)

Request envelope

Headers:
  • X-Barker-Event — same as event_type in the table above.
  • X-Barker-Signature — hex HMAC-SHA256 of the raw request body with your webhook secret. Always verify this before trusting the payload.
We expect a 2xx response within 10 seconds. Any other status (or a timeout) counts as a failure.

Retries

Failed deliveries are retried up to 3 attempts total (the original try plus 2 retries). The full attempt history and last response code is visible in the Portal under each delivery row (attempts, statuspending / delivered / failed, response code, response body excerpt). If your endpoint is down longer than the retry budget, the event row is durably stored — you can manually replay from the Portal once you’re back up.

Verifying the signature

The signature is HMAC-SHA256 over the exact bytes of the request body, hex-encoded. Verify on the raw bytes, not after JSON.parse + re-stringify — once you re-serialize, byte equivalence breaks (key order, whitespace, number formatting all differ across runtimes).

Idempotency

Network failures + retries mean you may receive the same delivery more than once. Dedupe key depends on the event family: A header-based idempotency key is on the roadmap. If you have a use case that needs it sooner, email partners@barker.money. For the failure handling that pairs with these guarantees — RPC outages, chain reorgs, partner-side endpoint downtime — see Failure modes.

Configure in Portal

  1. Open Portal → Webhooks
  2. Add a destination URL (HTTPS only — we won’t deliver to plain HTTP)
  3. Pick the events you want
  4. Copy the secret that appears once on creation. We hash it after that — there’s no way to retrieve it later, only rotate.
While integrating, point the URL at webhook.site first to inspect the exact bytes and headers we send. Move to your real handler after you’re confident the signature verification is correct.

What about inbound webhooks?

Most partner integrations only need outbound events — we tell you when something changes on the chain or product side, and you react. If you have a hybrid flow where your system needs to push state into Barker (e.g. KYC tier promotion, off-chain reconciliation confirmation), there’s an authenticated POST /api/partner/webhooks/inbound endpoint — see the API Reference. Email us first if you think you need it; usually a normal API call is the simpler answer.