Security and Verification

How to verify webhook authenticity and secure your endpoints

Webhook security is critical for protecting your application from malicious attacks and ensuring data integrity. This guide covers everything you need to implement robust security for your Rise webhook endpoints.

Why webhook security matters

Without proper security measures, attackers could:

Send fake events

Trigger unauthorized actions in your system with fabricated webhook events

Replay old events

Duplicate transactions or operations by resending legitimate webhook data

Intercept webhook data

Access sensitive payment information transmitted over insecure connections

Overwhelm servers

Launch denial-of-service attacks against your webhook endpoints

Security architecture overview

Rise webhooks include multiple layers of security to protect your integration:

1. HTTPS encryption

   All data encrypted in transit between Rise and your endpoint

2. Signature verification

   Cryptographic proof that requests actually came from Rise

3. Timestamp validation

   Protection against replay attacks using time-based verification

4. Secret management

   Secure storage and handling of webhook secrets

Signature verification

Every Rise webhook includes a cryptographic signature that proves the request came from Rise.

SDK Installation: Install the Rise SDK to get secure, type-safe webhook verification: npm install @riseworks/sdk

How signatures work

1. Rise generates signature using your webhook secret and event data
2. Signature included in headers with timestamp information
3. Your endpoint verifies the signature matches expected value
4. Process event only if signature is valid

Signature header format

Rise includes the signature in the X-Rise-Signature header:

X-Rise-Signature: t=1640995200,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

• t= - Timestamp when the signature was generated
• v1= - The signature hash using HMAC-SHA256

Implementing signature verification

The Rise SDK provides a secure, type-safe way to verify webhook signatures. Here’s how to use it:

Node.js

import { WebhookValidator } from '@riseworks/sdk';

// Create validator instance with your webhook secret
const validator = new WebhookValidator({
  secret: process.env.RISE_WEBHOOK_SECRET,
  tolerance: 600 // 10 minutes (default)
});

// Express.js middleware example
app.use('/rise-webhooks', express.raw({ type: 'application/json' }));

app.post('/rise-webhooks', async (req, res) => {
  const signature = req.headers['x-rise-signature'];
  
  try {
    // Verify signature and get validated event (uses default tolerance)
    const event = validator.validateEvent(req.body, signature);
    
    // For high-security scenarios, you can override tolerance:
    // const event = validator.validateEvent(req.body, signature, { tolerance: 60 });
    
    // Event is now verified and typed - process it
    handleWebhookEvent(event);
    
    res.status(200).json({ received: true });
  } catch (error) {
    console.error('Webhook verification failed:', error.message);
    res.status(400).send('Invalid signature');
  }
});

SDK Benefits: The Rise SDK handles all signature verification, timestamp validation, and type safety automatically. It also provides TypeScript types for all webhook events.

HTTPS recommendations

HTTPS is recommended for production webhook endpoints to protect data in transit, though Rise supports both HTTP and HTTPS endpoints.

Rise webhooks work with both HTTP and HTTPS endpoints. For production environments handling sensitive financial data, HTTPS is recommended for security. HTTP endpoints are perfectly suitable for development, testing, and localhost environments.

Why HTTPS is recommended

Data encryption

Prevents interception of sensitive payment data during transmission

Authentication

Ensures you’re communicating with Rise’s legitimate servers

Integrity

Prevents tampering with webhook data during transmission

Compliance

Required for PCI DSS and financial data protection standards

For production environments, HTTPS with a valid SSL certificate is recommended. For development and testing, HTTP endpoints (including localhost and ngrok) work perfectly fine. Use the Rise app’s test feature to verify your endpoint is properly configured.

Preventing replay attacks

Replay attacks occur when an attacker intercepts a valid webhook and sends it again later.

How replay protection works

1. Rise includes timestamp in every webhook signature
2. Your endpoint checks timestamp against current time
3. Reject old requests outside tolerance window
4. Log suspicious activity for monitoring

Timestamp validation with SDK

The Rise SDK automatically handles timestamp validation with configurable tolerance. You can set a default tolerance in the constructor and override it per validation call:

import { WebhookValidator } from '@riseworks/sdk';

// Create validator with default tolerance (10 minutes)
const validator = new WebhookValidator({
  secret: process.env.RISE_WEBHOOK_SECRET,
  tolerance: 600 // 10 minutes (default)
});

// Use default tolerance
const event = validator.validateEvent(req.body, signature);

// Override tolerance for high-security scenarios
const strictEvent = validator.validateEvent(req.body, signature, { 
  tolerance: 60 // 1 minute for high security
});

// Override tolerance for systems with clock sync issues
const lenientEvent = validator.validateEvent(req.body, signature, { 
  tolerance: 900 // 15 minutes for clock sync issues
});

Choosing tolerance windows

10 minutes (600 seconds)

Recommended for most applications

Provides good security while allowing for reasonable network delays and clock differences between servers.

1 minute (60 seconds)

High security environments

Maximum security but may cause issues if your server has clock synchronization problems or high network latency.

15 minutes (900 seconds)

Systems with clock issues

For systems with known clock synchronization issues, but reduces replay attack protection.

Don’t set tolerance to 0 seconds - this disables replay protection entirely and may cause legitimate webhooks to fail.

Secret management

Webhook secrets are critical security credentials that require careful handling.

Secret storage best practices

Environment variables

Never hardcode secrets in source code - use environment variables instead

Secure vaults

Use AWS Secrets Manager, HashiCorp Vault, or similar secure storage systems

Encryption at rest

Encrypt secret storage and limit access to authorized personnel only

Access control

Implement role-based access control for viewing and modifying secrets

Common security pitfalls

Avoid these common webhook security mistakes:

Don't do this

// WRONG: Skipping signature verification
app.post('/webhooks', (req, res) => {
  // Processing without verification - DANGEROUS!
  handleEvent(req.body);
  res.status(200).send('OK');
});

// WRONG: Using HTTP in production
const webhookUrl = 'http://mysite.com/webhooks'; // Insecure!

// WRONG: Hardcoded secrets
const secret = 'whsec_abc123'; // Never do this!

// WRONG: No timestamp validation
function verifySignature(payload, signature, secret) {
  // Missing timestamp check allows replays
  return crypto.createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex') === signature;
}

Testing your security implementation

Use the Rise app’s test webhook feature to verify your security implementation:

1. Send valid test events

   Confirm your endpoint properly processes legitimate webhook events

2. Test with invalid signatures

   Verify your endpoint correctly rejects webhooks with bad signatures

3. Monitor delivery results

   Check the delivery history for any security-related errors or failures

Security checklist

Before deploying to production, verify your implementation:

Signature verification

• Webhook signature is verified for every request
• Invalid signatures are rejected with 400 status
• Secret is stored securely (not hardcoded)
• HMAC comparison uses constant-time comparison

Timestamp validation

• Timestamp is checked against current time
• Appropriate tolerance window is configured
• Future timestamps are rejected
• Replay attacks are prevented

Transport security

• HTTPS is recommended for production
• Valid SSL certificate is installed
• HTTP redirects to HTTPS (if applicable)
• Strong TLS configuration

Error handling

• Security errors are logged appropriately
• Sensitive data is not leaked in error messages
• Rate limiting is implemented if needed
• Monitoring alerts are configured

What’s next?

Now that you’ve secured your webhook endpoints:

Webhook Management

Learn how to create, update, and manage your webhook endpoints

Event Types

Explore all available events and their data structures

Testing Tools

Testing your webhooks locally and troubleshooting common issues

Monitoring

Track security metrics and delivery performance

Security reminder: Webhook security is not optional. Always implement signature verification and consider HTTPS for production. The few extra lines of code can prevent serious security breaches.