Security

Key management, webhook security, and compliance.

Security requirements for BSync integrations.

API Key Storage

Store in environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager).
Never commit keys to git, even in .env files tracked by version control.
Use .env.example with placeholder values for documentation.

# .env.example
BSYNC_API_KEY=bsync_test_your_key_here
BSYNC_WEBHOOK_SECRET=whsec_your_secret_here

Server-Side Only

API keys and webhook secrets must only exist on your server:

Location	Allowed?
Server environment variables	Yes
Secrets manager	Yes
Browser JavaScript	No
Mobile app (client-side)	No
Public git repository	No
Client-side `.env` in frontend builds	No

All BSync API calls must originate from your backend.

Webhook Verification

Verify every webhook before processing. No exceptions.

import { verifySignature } from "@bsync/node-sdk";
 
const isValid = verifySignature({
  payload: rawBody,
  signature: req.headers["x-bsync-signature"],
  secret: process.env.BSYNC_WEBHOOK_SECRET,
});
 
if (!isValid) {
  return res.status(401).send("Invalid signature");
}

Use express.raw() or equivalent to preserve the raw body. Re-serializing JSON breaks HMAC verification.

Replay Protection

Verify X-BSYNC-SIGNATURE on every request.
Deduplicate by eventId — store processed event IDs.
Confirm payment status via getStatus() before fulfilling orders.

An attacker cannot forge webhooks without your webhook secret. A replayed legitimate webhook is harmless if you deduplicate by eventId.

HTTPS

Required for all production endpoints:

Your webhook receiver URL
successUrl and cancelUrl in payment creation
All API calls (enforced by BSync for redirect URLs)

Secret Rotation

API Keys

Create new key in Dashboard.
Update BSYNC_API_KEY in all services.
Deploy.
Revoke old key.
Monitor for 401 errors on old key.

Webhook Secrets

Generate new secret in Dashboard.
Update BSYNC_WEBHOOK_SECRET in your webhook receiver.
Deploy.
Old secret stops working immediately — time the rotation during low traffic.

Rotate at least quarterly, or immediately after suspected compromise.

Rate Limits

BSync enforces per-API-key rate limits. When exceeded:

HTTP 429 with Retry-After header
SDK RateLimitError with retryAfter property

Do not hammer the API. Implement backoff and cache status responses where appropriate.

Monitoring

Monitor for security-relevant events:

Event	Action
Repeated 401 errors	Possible key leak or misconfiguration
Invalid webhook signatures	Possible attack or secret mismatch
Unusual payment volume	Review for fraud
`dead_letter` webhook deliveries	Fix webhook endpoint

Audit Logs

Log these for every integration event:

API calls: requestId, endpoint, paymentId, timestamp
Webhooks: eventId, eventType, paymentId, signature valid/invalid
Key rotation: who rotated, when, which key

Retain logs for at least 90 days for dispute resolution.

Was this page helpful?

Best Practices

FAQ