Braintree

Braintree is PayPal’s payment processing platform, used by merchants to accept cards, digital wallets, and other payment methods through a hosted gateway. Two distinct kinds of automated traffic are associated with it, and it’s worth separating them clearly. The first is outbound: a merchant’s own server calling Braintree’s API (api.braintreegateway.com) to create transactions, tokenize payment methods, or manage subscriptions. The second — the traffic relevant to a bot-management context — is inbound: Braintree’s servers calling a merchant-configured webhook endpoint to push real-time notifications about events like a completed subscription charge, a dispute, or a disbursement.

Unlike a search crawler or a monitoring probe, Braintree does not publish a distinct, memorable user-agent string for its webhook calls. Its authentication model is built around a different mechanism entirely: every webhook notification carries a signed payload (bt_signature and bt_payload) that the receiving application verifies cryptographically using its Braintree private key, via the official SDK. Braintree also publishes its production and sandbox IP addresses and domains in a JSON file specifically so merchants can allowlist its infrastructure at the network layer, in addition to signature verification. Because this traffic sits directly in a payment flow, DataDome classifies Braintree under security intelligence and payment infrastructure — automated, essential traffic where spoofing risk carries real financial consequence rather than a mere nuisance.

• Transaction and subscription webhooks. Notifications such as SubscriptionChargedSuccessfully, settlement batch summaries, and transaction status changes keep merchant systems synchronized with Braintree’s ledger.
• Dispute and chargeback notifications. Webhooks fire when a dispute is opened, lost, or won, letting merchant systems trigger the appropriate fulfillment or refund workflow automatically.
• Marketplace sub-merchant onboarding. SubMerchantAccountApproved and SubMerchantAccountDeclined webhooks confirm the outcome of onboarding checks (OFAC, Mastercard MATCH, KYC) for platforms running Braintree Marketplace.
• Disbursement notifications. Webhooks confirm when funds have been disbursed to a merchant or sub-merchant account.
• Account security event notifications. Events like api_key_created, tokenization_key_destroyed, and ip_restrictions_changed notify administrators of changes to their own Braintree account configuration.
• Server-to-server API calls. Direct calls from a merchant’s backend to Braintree’s API to process payments, separate from the webhook direction but part of the same trusted infrastructure relationship.

Because this traffic sits inside a payment and fraud-notification pipeline, the stakes of impersonation are materially higher than with an SEO crawler or a search bot:

• Forged webhook payloads. An attacker who discovers a merchant’s webhook endpoint URL can attempt to POST a fabricated notification — for example, a fake SubscriptionChargedSuccessfully or DisbursementException event — hoping the receiving application processes it without verifying the signature.
• Signature-verification bypass. If an integration is misconfigured to log and act on webhook payloads before or without calling the signature-parsing method, it becomes trivially exploitable by anyone who can reach the endpoint.
• Endpoint enumeration. Because webhook URLs are merchant-configured rather than standardized, attackers sometimes probe common or guessable paths (/webhooks/braintree, /braintree/webhook) looking for unprotected receivers.
• Replay attacks. A previously valid, correctly signed webhook payload could in principle be resent; applications that don’t check for duplicate or already-processed event IDs are exposed to this.
• Traffic exploiting the no-denylist model. Braintree does not offer a way to block or denylist its own outbound IPs from the merchant side (only an allowlist for inbound Control Panel and API access), which means merchants can’t simply “wall off” this traffic the way they might with a low-value crawler — any control has to happen at the signature-verification and application layer.

The critical mitigating fact: a forged webhook cannot alter the real state of a merchant’s Braintree account or trigger an actual disbursement or charge. Braintree’s own transaction and settlement records are authoritative and are not affected by spoofed traffic arriving at a merchant’s receiving endpoint. The risk is entirely local — a merchant application incorrectly trusting an unverified payload and acting on it as if it were real (e.g., marking an order as paid, releasing goods, or reversing a dispute outcome that never happened).

If your systems are receiving traffic from Braintree, it’s almost always because your integration configured a webhook destination URL in the Braintree Control Panel, or your backend is making direct API calls as part of normal payment processing. A few things worth knowing:

• Delivery is event-driven, not scheduled. Webhook volume tracks how often relevant events occur in your account — subscription charges, disputes, disbursements — rather than following a fixed polling interval.
• This traffic is not optional infrastructure. Unlike a search crawler, blocking Braintree’s traffic doesn’t cost visibility — it breaks payment processing, dispute handling, and reconciliation directly.
• Domains, not just IPs, matter. Braintree’s production traffic resolves across api.braintreegateway.com, www.braintreegateway.com, gstatic.braintreegateway.com, and payments.braintree-api.com; sandbox traffic uses parallel sandbox.braintreegateway.com-prefixed domains.
• Client-side calls are a separate category. Encrypted calls made directly from a customer’s browser via Braintree’s client SDKs (for example, generating a payment method nonce) are not subject to any IP or hostname allowlist and won’t match the same source-IP profile as server-to-server or webhook traffic.

1. Do not rely on a user-agent string. Braintree does not publish a fixed, distinctive user-agent for webhook delivery the way search or SEO crawlers do, so user-agent filtering isn’t a meaningful control here.
2. Verify the cryptographic signature on every webhook.This is the primary and strongest authentication mechanism: parse bt_signature and bt_payload through the official SDK method (WebhookNotification.parse or equivalent) before trusting any content in the payload. A signature mismatch means the request did not originate from Braintree, regardless of source IP.
3. Cross-check the source IP against Braintree’s published list, available as JSON at assets.braintreegateway.com/json/ips.json and mirrored on the Braintree IP Addresses documentation page, refreshed whenever Braintree updates its infrastructure.
4. Confirm the domain resolution matches Braintree’s documented FQDNs for outbound calls your systems make to Braintree — this protects against DNS-based interception rather than inbound spoofing, but is part of the same verification posture.
5. Reject unsigned or malformed payloads outright, and log the attempt — a webhook endpoint receiving a request without a valid bt_signature should never proceed to business logic.
6. Guard against replay. Track processed event or transaction IDs and reject duplicates, since signature validity alone doesn’t guarantee a payload hasn’t been captured and resent.
7. Treat IP verification as a secondary signal, not a substitute for signature checking. Braintree’s own documentation frames IP allowlisting as a means to ensure uninterrupted connectivity, not as the primary security control — signature verification is.

Blocking genuine Braintree traffic is fundamentally different from blocking a search or SEO crawler: it doesn’t cost visibility, it breaks payment processing. Braintree itself notes that it does not currently offer merchants a way to denylist its own IPs, and any attempt to do so on the merchant side risks:

• missed transaction, subscription, or dispute webhooks, leading to desynchronized order and fulfillment state;
• failed settlement reconciliation if disbursement notifications never arrive;
• broken sub-merchant onboarding flows for marketplace integrations; and
• outright payment processing failures if the outbound API domains and IPs aren’t allowlisted on a restrictive firewall.

Restricting or scrutinizing traffic claiming to be Braintree makes sense only when:

• a request fails signature verification and therefore isn’t genuinely from Braintree;
• traffic is hitting a webhook path that was never configured in your Braintree Control Panel;
• an old or decommissioned integration’s webhook URL is still receiving calls and needs to be retired at the source; or
• you’re auditing for endpoint exposure rather than deciding whether to allow the vendor relationship itself.

• Make signature verification non-negotiable. Every webhook handler should call the SDK’s parse method before any other logic runs, and should fail closed (reject, log, alert) on an invalid signature rather than failing open.
• Allowlist Braintree’s published IPs and domains on your firewall for both directions — outbound calls to api.braintreegateway.com and inbound webhook delivery — pulling current values from assets.braintreegateway.com/json/ips.json rather than hardcoding a static list:

# Example (illustrative only — pull current ranges from
# assets.braintreegateway.com/json/ips.json before applying)
location /webhooks/braintree {
    allow <current-braintree-ip-range>;
    deny all;
}

• Use a dedicated, unguessable webhook path rather than a predictable one, reducing exposure to endpoint enumeration even though signature verification remains the real control.
• Enforce idempotency. Store processed transaction/event identifiers and reject repeats, closing the replay gap that IP and signature checks alone don’t cover.
• Separate Braintree’s own Control Panel IP/hostname restrictions from your webhook-receiving security. The Control Panel allowlist governs who can access your Braintree account and API — it has no bearing on securing the endpoint that receives Braintree’s webhook calls.
• Log and alert on signature failures specifically, since a spike in invalid-signature attempts against a webhook path is a much stronger indicator of an attack than raw request volume.

Braintree should be treated as trusted payment infrastructure rather than general bot traffic, but “trusted” here means cryptographically verified, not merely IP-matched. Because Braintree does not expose a distinguishing user-agent and explicitly does not support denylisting its own traffic, the correct posture is to authorize its published IP ranges and domains as a connectivity safeguard while treating webhook signature verification as the actual security boundary. Any traffic claiming to be Braintree that fails signature verification should be rejected and logged regardless of its source IP, since a valid-looking IP address proves nothing about payload authenticity in a payment context.