<- Back To Blog

Enterprise-Grade Security for ERPNext Integration

OrderWeave Team
OrderWeave Team · December 6, 2024

When you integrate your ERP system with external services, security isn't optional—it's mission-critical. Your ERPNext system contains sensitive business data: product pricing, inventory levels, supplier information, and customer orders. Any vulnerability in your integration could expose this data to unauthorized access or tampering.

That's why OrderWeave is built on HMAC-SHA256 signature authentication, the same cryptographic standard used by Amazon Web Services, GitHub, and Stripe. This blog post explains how we secure your data end-to-end.

Why HMAC-SHA256?

Traditional API authentication methods like API keys have significant limitations:

  • API keys are static: If an API key is compromised, an attacker can use it indefinitely until you rotate it manually
  • No message integrity: API keys authenticate the sender but don't verify that the message wasn't tampered with in transit
  • Vulnerable to replay attacks: An attacker can intercept and resend valid requests
  • Difficult rotation: Changing API keys requires coordinated updates across all systems

HMAC-SHA256 (Hash-based Message Authentication Code with SHA-256) solves all these problems by using cryptographic signatures instead of static tokens.

How HMAC Works

HMAC-SHA256 combines three security mechanisms:

  1. Shared Secret: Both ERPNext and OrderWeave possess a shared secret key that never leaves either system
  2. Message Hashing: Each request is hashed using SHA-256 with the shared secret
  3. Signature Verification: OrderWeave recomputes the signature and verifies it matches

Because the signature is computed from both the message content and the shared secret, any modification to the message invalidates the signature.

The Authentication Flow

Let's walk through what happens when ERPNext sends a product update to OrderWeave:

Step 1: ERPNext Prepares the Request

When you update an item in ERPNext, the OrderWeave app:

  1. Collects the item data (name, SKU, price, stock, images, etc.)
  2. Generates a UTC timestamp (current time in seconds)
  3. Serializes the data to JSON with sorted keys (for consistency)
  4. Constructs a signature payload: timestamp:json_body

Step 2: Signature Generation

ERPNext computes the HMAC-SHA256 signature: 

signature_payload = f"{timestamp}:{json_body}"
hmac_secret = base64_decode(secret_from_settings)
signature = HMAC-SHA256(hmac_secret, signature_payload)
signature_b64 = base64_encode(signature)

This produces a cryptographically secure signature that's unique to this specific message and timestamp.

Step 3: Request Transmission

ERPNext sends the request with these HTTP headers:

  • X-OrderWeave-Signature: Base64-encoded HMAC signature
  • X-OrderWeave-Timestamp: Unix timestamp (seconds)
  • X-Tenant-Id: Your tenant identifier
  • Content-Type: application/json

Notice that the shared secret itself is never transmitted—only the signature derived from it.

Step 4: OrderWeave Validation

When OrderWeave receives the request, it performs multiple security checks:

  1. Timestamp Validation
    • Rejects requests more than 5 minutes old (configurable)
    • Rejects requests with future timestamps
    • Prevents replay attacks using expired signatures
  2. Tenant Lookup
    • Finds the tenant by slug or UUID
    • Retrieves the stored HMAC secret for that tenant
    • Ensures tenant isolation (no cross-tenant access)
  3. Signature Recomputation
    • Reconstructs the signature payload from the request body and timestamp
    • Computes HMAC-SHA256 using the tenant's secret
    • Generates the expected signature
  4. Constant-Time Comparison
    • Uses hmac.compare_digest() for timing attack resistance
    • Compares received signature with expected signature
    • Returns 200 OK if match, 401 Unauthorized if mismatch

Four Layers of Security

1. Message Integrity

Because the signature is computed from the entire message body, any tampering is immediately detectable:

  • Changed product prices? Signature invalid.
  • Modified stock quantities? Signature invalid.
  • Altered item codes? Signature invalid.

Even a single character change invalidates the signature, ensuring that OrderWeave processes exactly what ERPNext sent—no more, no less.

2. Replay Attack Prevention

The timestamp embedded in each signature creates a time-limited validity window:

  • Requests older than 5 minutes are automatically rejected
  • An attacker who intercepts a valid request cannot replay it later
  • Even if network logs are compromised, signatures quickly expire

The 5-minute window balances security with clock skew tolerance. If your ERPNext server and OrderWeave's servers have slightly different times, the request still succeeds.

3. Timing Attack Resistance

OrderWeave uses constant-time comparison to prevent timing attacks:

  • Traditional string comparison exits early on the first mismatch
  • An attacker could measure response times to guess signatures byte-by-byte
  • hmac.compare_digest() always takes the same time regardless of where the mismatch occurs

This is a subtle but critical defense against sophisticated attackers.

4. No Password Transmission

Unlike basic authentication or API keys, the shared secret never travels over the network:

  • The secret stays in your ERPNext configuration
  • The secret stays in OrderWeave's database
  • Only the signature (a cryptographic hash) is transmitted
  • Even if HTTPS is somehow compromised, the secret remains safe

How to Set Up HMAC Authentication

Setting up OrderWeave's HMAC authentication is straightforward:

Step 1: Generate a Shared Secret

Use OpenSSL to generate a 256-bit (32-byte) random secret: 

openssl rand -base64 32

This produces a string like: 8XMvP7Q9R2S5T6U3V4W1X0Y9Z8A7B6C5D4E3F2G1H0I=

Step 2: Configure OrderWeave (Ingestion Database)

OrderWeave's team will add the secret to your tenant record: 

UPDATE tenants
SET hmac_secret = '8XMvP7Q9R2S5T6U3V4W1X0Y9Z8A7B6C5D4E3F2G1H0I='
WHERE slug = 'your_company_slug';

Step 3: Configure ERPNext

In ERPNext, navigate to: Setup → OrderWeave Settings

  1. Tenant ID: Your company slug (e.g., lighting_co_ke)
  2. HMAC Secret: Paste the base64-encoded secret
  3. Ingestion URL: https://ingest.orderweave.com/api/v1/ingest
  4. Click Save

Step 4: Verify It Works

Update any item in ERPNext and check the logs: 

# ERPNext logs
tail -f ~/frappe-bench/logs/sync_delta_detector.log | grep "HMAC"

# OrderWeave logs (via support)
# Look for: "HMAC authenticated successfully for tenant: your_company_slug"

Additional Security Measures

HMAC authentication is just one layer of OrderWeave's security architecture:

TLS/SSL Encryption

All communication is encrypted in transit using TLS 1.2+ with strong cipher suites. Even though HMAC protects message integrity, encryption prevents eavesdropping on sensitive business data.

AES-256 Encryption at Rest

Data stored in OrderWeave's databases (audit logs, product mappings, tenant configurations) is encrypted at rest using AES-256, the same encryption standard used by banks and government agencies.

Multi-Tenancy Isolation

Every OrderWeave query filters by tenant_id to ensure complete data isolation:

  • Tenant A cannot access Tenant B's data
  • Audit logs, product mappings, and routing rules are strictly segregated
  • JWT-based access control enforces tenant boundaries in the dashboard

Comprehensive Audit Trails

Every API request, every sync operation, and every authentication attempt is logged with:

  • Timestamp (UTC, millisecond precision)
  • Tenant ID and user ID (if applicable)
  • Request payload and response status
  • Authentication method (HMAC signature or JWT)
  • Processing duration

These logs provide complete traceability for compliance audits and security investigations.

Backward Compatibility

If you're an existing OrderWeave customer using API keys, don't worry:

  • API keys still work for dashboard access and read-only operations
  • No breaking changes: Your existing integration continues functioning
  • Gradual migration: Upgrade to HMAC authentication at your own pace
  • Dashboard access: API keys remain supported for non-ingestion endpoints

Conclusion

Security isn't a feature—it's a fundamental requirement for any enterprise integration. OrderWeave's HMAC-SHA256 authentication provides:

  • 🔒 Message integrity: Detect any tampering instantly
  • ⏱️ Replay attack prevention: Time-limited signatures expire after 5 minutes
  • 🛡️ Timing attack resistance: Constant-time signature comparison
  • 🔐 No password transmission: Shared secrets never leave your systems
  • 📝 Complete audit trails: Full traceability for every operation

When you integrate ERPNext with your e-commerce stores, you shouldn't have to compromise on security. With OrderWeave, you don't have to.

Ready to secure your ERPNext integration? Contact us or learn more about our security features.

Get all of our updates directly to your inbox.