Skip to content

feat(ibex): record Bridge deposits from IBEX Hub's organization webhook (ENG-891) - #545

Merged
islandbitcoin merged 2 commits into
mainfrom
eng-891-ibex-org-webhook
Nov 20, 2026
Merged

islandbitcoin merged 2 commits into
mainfrom
eng-891-ibex-org-webhook

Conversation

@islandbitcoin

Copy link
Copy Markdown
Contributor

What

Flash now hears from IBEX the moment a Bridge virtual-account deposit lands. IBEX Hub's organization webhook posts to a new route, POST /hub/transactions. A crypto receive there is recorded right away: ERPNext settle row, deposit row Completed, user notification. Before, it waited up to an hour for the matcher. The dead /crypto/receive route is removed. This is ENG-891, PR 2 of 3.

Why

/crypto/receive (added in #413, July) never received a call:

  • Nothing gave IBEX its URL. webhook-config.ts built it and no code read it, and createCryptoReceiveInfo registers no webhook.
  • It expected flat tx_hash/address/amount fields that IBEX does not send.

IBEX's only notice of a crypto credit is its organization-level webhook (POST /webhooks, event Transactions). Production has none registered: GET /webhooks returned 0 on 11/20. Since #543 the hourly matcher records these deposits, but up to an hour late.

How

Route (src/services/ibex/webhook-server/routes/hub-transactions.ts), mounted before the server's JSON parser:

  1. Rate limit (1200/min, since the webhook reports every transaction).
  2. Hub IP allowlist, ibex.webhook.hub.allowedIps. Empty disables it, like the legacy allowedIps.
  3. Raw body.
  4. Ed25519 signature check (middleware/verify-hub-signature.ts), Standard Webhooks style:
    • signs {webhook-id}.{webhook-timestamp}.{raw body}, header v1a,<base64>, any valid entry of several;
    • 5 minute replay window;
    • key from ibex.webhook.hub.publicKey (base64 raw 32 bytes, as Create Webhook returns it);
    • with no usable key every delivery gets 503 and an error log.
  5. 200 before any work, because IBEX waits 4 s, retries once, then drops the event.
  6. Only transactionTypeId 9 is acted on. Every delivery gets one info log line (event, type, status, webhook id; no body).

Recording (recordIbexCreditSignal in src/app/bridge/match-ibex-deposits.ts). Per IBEX's guidance the body is not trusted. The function:

  • reads the transaction back (GET /v2/transaction/{id}: status, wallet, amount) and its tx hash (/details networkId);
  • requires completed;
  • finds the payment_processed Bridge deposit with that hash;
  • checks the credit landed on that customer's USDT wallet;
  • records through the same recordIbexCryptoReceive as the matcher. It is locked on the hash and skips a processed receive, so the webhook and the matcher never both notify.

When there is no deposit with that hash yet (Bridge's event can trail IBEX's by a minute or two), it records nothing. The hourly matcher picks it up, and PR 3 closes that gap from the Bridge side.

Removed: routes/crypto-receive.ts and its config entries. Its spec became test/flash/unit/app/bridge/record-crypto-receive.spec.ts (14 of 16 kept; the 2 dropped tested only the route's HTTP layer: middleware order and the 400 on a non-USDT payload). Docs that named the route are updated.

Rollout (manual steps)

  1. Merge and deploy. The route answers 503 until step 3, and nothing calls it yet.
  2. Register the webhook. This is a production write to IBEX, run by the owner on the jumpbox. The script creates it only if no webhook with that URL exists, and prints the id and publicKey (public, not a secret):
    bash ibex-register-hub-webhook.sh do-tor1-flash-k8s-prod https://ibex.flashapp.me/hub/transactions
  3. Deployments PR: set ibex.webhook.hub.publicKey and ibex.webhook.hub.allowedIps (production 34.148.92.171, 35.196.168.24; sandbox 35.243.242.121, 34.74.236.191, per docs.poweredbyibex.io/webhooks/security.md), then apply.
  4. Verify: IBEX Hub webhook delivery lines appear on the ibex webhook pod for ordinary transactions, with no Rejected IBEX Hub webhook delivery lines.

Tests

  • verify-hub-signature.spec.ts (20): valid, tampered body, other key, moved webhook-id, either side of the window and its edge, missing headers, no v1a, several signatures, key parsing, and the middleware's 503/401/400/pass.
  • hub-transactions.spec.ts: middleware order, 200 before the work, only type 9 handed on, a failing recorder still 200.
  • hub-transactions-http.spec.ts: a real Express server with the JSON parser after the route. A signed body with odd whitespace verifies, a forged or unsigned one gets 401, and a signed Lightning transaction gets 200 and records nothing.
  • match-ibex-deposits.spec.ts: recordIbexCreditSignal records, ignores non-receives and pending/failed ones, refuses a credit on another wallet, waits on a missing deposit, and reports each read or record failure.
  • start-guard.spec.ts: the hub router is mounted before the JSON parser.
  • Local: 58 suites, 869 tests pass across app/bridge, services/ibex, services/bridge, servers and config. eslint, prettier 3.6.2 and typos are clean on the changed lines. tsc shows only the two graphql*-server.ts errors the previous tree also shows locally (CI's check passes).

Not tested: a real IBEX Hub delivery. That waits for the registration in rollout step 2.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Gn2VCc25BAQjEu33uLycvP

…ok (ENG-891)

IBEX's only notice of a USDT credit on a Bridge deposit address is its
organization-level webhook (POST /webhooks, event "Transactions"), which
Flash never registered. The /crypto/receive route it had instead was never
given to IBEX and expected a payload IBEX does not send; it is removed.

POST /hub/transactions takes the organization webhook: hub IP allowlist,
raw body, Ed25519 signature over "{webhook-id}.{webhook-timestamp}.{body}"
with the webhook's public key (ibex.webhook.hub.publicKey; 503 until set),
a 5 minute replay window, then 200 before any work. A crypto receive is read
back from IBEX (status, wallet, amount, tx hash) and recorded through
recordIbexCryptoReceive only when a payment_processed Bridge deposit has
its tx hash and the credit landed on that customer's USDT wallet. Every
other transaction is ignored. The hourly matcher stays the backstop, since
IBEX delivers at most once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Gn2VCc25BAQjEu33uLycvP
@linear

linear Bot commented Nov 20, 2026

Copy link
Copy Markdown

ENG-891

…G-891)

Review fixes for the IBEX Hub webhook route.

validateIbexHubIp had no test. The IP spec now loads the middleware with a
mocked config (legacy list 198.51.100.9, hub list 203.0.113.4) and checks
that a hub-listed sender passes, that a sender on the legacy list only or
on neither list gets 403 without next(), that an empty hub list passes any
sender, and that the legacy gate still reads the legacy list. The HTTP spec
adds a second app loaded with the hub list set, where a signed delivery from
127.0.0.1 gets 403 and nothing is recorded.

IBEX_CRYPTO_RECEIVE_TYPE_ID was declared in both the route and the matcher.
The matcher now exports it and the route imports it, so the route's filter
and recordIbexCreditSignal's check cannot drift apart.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Gn2VCc25BAQjEu33uLycvP

@bobodread876 bobodread876 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simon review clean after one fix round; CI green on f6d054c with the new hub specs run.

@islandbitcoin
islandbitcoin merged commit d3bf36d into main Nov 20, 2026
16 checks passed
@islandbitcoin
islandbitcoin deleted the eng-891-ibex-org-webhook branch November 20, 2026 15:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants