Repository navigation
feat(ibex): record Bridge deposits from IBEX Hub's organization webhook (ENG-891) - #545
Merged
Merged
Conversation
…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
…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
approved these changes
Nov 20, 2026
bobodread876
left a comment
Collaborator
There was a problem hiding this comment.
Simon review clean after one fix round; CI green on f6d054c with the new hub specs run.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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/receiveroute is removed. This is ENG-891, PR 2 of 3.Why
/crypto/receive(added in #413, July) never received a call:webhook-config.tsbuilt it and no code read it, andcreateCryptoReceiveInforegisters no webhook.tx_hash/address/amountfields that IBEX does not send.IBEX's only notice of a crypto credit is its organization-level webhook (
POST /webhooks, eventTransactions). Production has none registered:GET /webhooksreturned 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:ibex.webhook.hub.allowedIps. Empty disables it, like the legacyallowedIps.middleware/verify-hub-signature.ts), Standard Webhooks style:{webhook-id}.{webhook-timestamp}.{raw body}, headerv1a,<base64>, any valid entry of several;ibex.webhook.hub.publicKey(base64 raw 32 bytes, as Create Webhook returns it);200before any work, because IBEX waits 4 s, retries once, then drops the event.transactionTypeId9 is acted on. Every delivery gets one info log line (event, type, status, webhook id; no body).Recording (
recordIbexCreditSignalinsrc/app/bridge/match-ibex-deposits.ts). Per IBEX's guidance the body is not trusted. The function:GET /v2/transaction/{id}: status, wallet, amount) and its tx hash (/detailsnetworkId);completed;payment_processedBridge deposit with that hash;recordIbexCryptoReceiveas 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.tsand its config entries. Its spec becametest/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)
publicKey(public, not a secret):bash ibex-register-hub-webhook.sh do-tor1-flash-k8s-prod https://ibex.flashapp.me/hub/transactionsibex.webhook.hub.publicKeyandibex.webhook.hub.allowedIps(production34.148.92.171,35.196.168.24; sandbox35.243.242.121,34.74.236.191, per docs.poweredbyibex.io/webhooks/security.md), then apply.IBEX Hub webhook deliverylines appear on the ibex webhook pod for ordinary transactions, with noRejected IBEX Hub webhook deliverylines.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, nov1a, 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:recordIbexCreditSignalrecords, 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.app/bridge,services/ibex,services/bridge,serversandconfig. eslint, prettier 3.6.2 and typos are clean on the changed lines.tscshows only the twographql*-server.tserrors 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