[BWS] Feat: webhooks support for external services - #4216
Open
Gamboster wants to merge 7 commits into
Open
Conversation
Gamboster
marked this pull request as draft
August 10, 2026 19:29
Gamboster
force-pushed
the
feat/externalServicesWebhooks
branch
from
August 13, 2026 15:56
0ee627c to
15d9dc4
Compare
Gamboster
force-pushed
the
feat/externalServicesWebhooks
branch
from
August 18, 2026 19:04
aae7a67 to
0b13750
Compare
Gamboster
marked this pull request as ready for review
August 19, 2026 14:06
Gamboster
force-pushed
the
feat/externalServicesWebhooks
branch
from
August 19, 2026 18:07
bd4a5be to
5491731
Compare
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.
Description
Ticket Reference: RN-2714
This PR adds webhook endpoints for all six partners so BWS can react to status changes (processing, completed, failed, refunded, etc.) in real time instead of relying purely on client-side polling, while guarding against the usual webhook pitfalls: unverified senders, duplicate/retried deliveries, and out-of-order delivery.
Webhook processing will be rolled out gradually: Not all endpoints will be operational immediately. Initially, we will enable the Moonpay webhook endpoint until we verify that everything is working as expected with this single partner. (Until we enable webhooks in the configuration of each external service, the endpoints will not receive traffic.) Then we will continue with the other partners, one by one, until all are operational simultaneously.
The first thing we will do upon receiving a call is check that it is not a duplicate or out-of-order status and then send an event to Braze (a requirement of the marketing team). Any additional processing that needs to be done will be added in the future in another PR.
Changelog
POST /v1/service/{partner}/webhookroutes in a newsrc/lib/routes/webhooks.ts, with a shared handler that verifies the signature, persists the event, and always responds so the partner doesn't retry unnecessarily.Moonpay-Signature-V2: t=...,s=...), with support for both the standard and embedded webhook secrets.X-Signature-SHA256, including expiry (exp) enforcement.fast-json-stable-stringify-equivalent) serialization of the body, sent inX-Body-Signature.POST\n{path}\n{nonce}\n{body}, sent viaAuthorization: Bearer {apiKey}:{signature}:{nonce}.X-Sardine-Signature.POST /partners/api/v2/refresh-token), now fetched and cached per environment instead of a static secret.onramp_webhook_eventscollection (storage.ts) keyed by a deterministic id (partner + env + event + externalId + delivery version), so retried deliveries from a partner are safely ignored.src/lib/braze.ts) that fires a "BWS - ONRAMP Webhook Received" track event per unique delivery (skipped for duplicates/stale events and when no user id is available).userIdquery param to the signedwebhookStatusUrl/offrampWebhookV3Urlit generates, which Ramp echoes back on the webhook call.OnrampWebhookEventmodel (src/lib/model/onrampWebhookEvent.ts) as the common shape used across all partners' webhook handlers and storage.bws.example.config.js/config.ts) for webhook secrets/signing keys per partner and environment.test/integration/externalservices/*.test.ts) covering signature verification (valid/invalid/missing signature, missing secret configured), payload parsing, and error handling for each partner's new*HandleWebhookmethod.Testing Notes
bws.example.config.js) for signature verification to be enforced; if left unset, verification is skipped with a warning logged (useful for local testing without real credentials, but should be set in staging/production).npm testinpackages/bitcore-wallet-service) exercise the signature verification and field-mapping logic per partner in isolation, including duplicate/invalid-signature/missing-header/missing-config edge cases.