This guide will walk you through setting up your first Rise webhook in under 10 minutes. By the end, you’ll have a working webhook endpoint that receives real-time notifications from Rise.

​
Prerequisites

Before you start, make sure you have:

Rise Account

A Rise account with a RiseID (get one at app.rise.works)

Server Setup

A server that can receive HTTP POST requests

HTTPS Recommended

HTTPS recommended for production (HTTP works for development/testing)

API Credentials

Your Rise API credentials from the dashboard

​
Step 1: Create your webhook endpoint

First, create an endpoint on your server to receive webhook events. Your endpoint should:
  • Accept POST requests
  • Return a 200 status code quickly
  • Handle the JSON payload Rise sends
const express = require('express');
const app = express();

app.use(express.json());

app.post('/rise-webhooks', (req, res) => {
  const event = req.body;

  // Handle the event
  console.log('Received event:', event.event_type);
  console.log('Event ID:', event.id);
  console.log('Event data:', event);

  // Respond quickly with 200
  res.status(200).json({ received: true });
});

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

​
Step 2: Register your webhook in the Rise app

Now you’ll register your webhook endpoint using the Rise app’s user interface:
1

Navigate to webhooks

Open the Rise app and navigate to the Developer section, then click on “Webhooks” in the sidebar menu.
2

Create new webhook

Click “Create Webhook” to add a new webhook endpoint.
3

Configure webhook details

Fill in the webhook details:
  • Endpoint URL: https://your-server.com/rise-webhooks
  • Secret: Enter a secure secret string for signature verification (e.g., whsec_your_secure_random_string)
  • Description: Optional description for your webhook
  • Event Types: Select the events you want to receive
  • Team: Choose company-level or specific team (optional)
4

Select event types

For this tutorial, select:
  • payment.sent - When a payment is successfully sent
  • payment.group.created - When a new payment group is created
5

Save configuration

Click “Create Webhook” to save your configuration. Remember the secret you entered - you’ll need it for signature verification.
Keep your webhook secret secure! You’ll need it for signature verification, and you can view it later in the webhook details page.

​
Step 3: Test your webhook

Rise provides a built-in testing feature directly in the app:
1

Access test feature

Go to your webhook details page in the Rise app and click the “Test Webhook” button.
2

Select event type

Choose an event type to test (e.g., payment.sent).
3

Send test event

Click “Send Test Event” to deliver a test payload to your endpoint.
4

Verify receipt

Check your server logs to confirm you received the test event.
You should see output similar to this in your server logs: 
Received event: payment.sent
Event ID: we-IQGikif4ja4A
Event data: { id: 'we-IQGikif4ja4A', object: 'event', created: 1751590453, ... }

​
Step 4: Add signature verification with Rise SDK

For security, verify that webhook requests actually come from Rise using the official Rise SDK: 
const express = require('express');
const { WebhookValidator } = require('@riseworks/sdk');

const app = express();

// Use raw body for signature verification
app.use('/rise-webhooks', express.raw({ type: 'application/json' }));

app.post('/rise-webhooks', (req, res) => {
  const signature = req.headers['x-rise-signature'];
  const secret = process.env.RISE_WEBHOOK_SECRET;

  try {
    // Validate webhook using Rise SDK WebhookValidator
    const riseValidator = new WebhookValidator({
      secret: secret,
      tolerance: 720 // 12 minutes tolerance
    });
    
    // Option 1: validateEvent (throws on failure)
    let event = riseValidator.validateEvent(req.body, signature);
    
    // Option 2: validateEventSafe (returns result object)
    const result = riseValidator.validateEventSafe(req.body, signature);
    if (!result.isValid) {
      console.error('Validation failed:', result.error);
      return res.status(400).json({ error: result.error });
    }
    event = result.event;

    // Signature is valid, process the event
    handleEvent(event);

    res.status(200).json({ 
      received: true,
      timestamp: new Date().toISOString(),
      event_type: event.event_type,
      event_version: event.event_version,
      idempotency_key: event.idempotency_key
    });
  } catch (error) {
    console.error('Webhook verification failed:', error.message);
    res.status(400).json({ 
      error: 'Webhook processing failed',
      message: error.message,
      timestamp: new Date().toISOString()
    });
  }
});
Use the exact same secret string you entered when creating the webhook. You can view it in your webhook details page in the Rise app if needed.

​
Installing the Rise SDK

To use the Rise SDK for webhook validation, install it in your project: 
# Using npm
npm install @riseworks/sdk

# Using yarn
yarn add @riseworks/sdk

# Using pnpm
pnpm add @riseworks/sdk
The SDK provides:
  • Class-based webhook validation using WebhookValidator
  • Type-safe webhook validation with full TypeScript support
  • Automatic signature verification with configurable tolerance
  • Proper error handling with detailed error messages
  • Support for multiple input types (string, Buffer, object)

​
Step 5: Handle events in your application

Now you can add business logic to handle specific events with full type safety: 
import type { 
  RiseWebhookEvent, 
  PaymentSentV1, 
  PaymentGroupCreatedV1, 
  DepositReceivedV1 
} from '@riseworks/sdk';

function handleEvent(event: RiseWebhookEvent) {
  switch (event.event_type) {
    case 'payment.sent':
      // Send confirmation email with full type safety
      sendPaymentConfirmation(event as PaymentSentV1);
      break;

    case 'payment.group.created':
      // Update order status with full type safety
      updateOrderStatus(event as PaymentGroupCreatedV1);
      break;

    case 'deposit.received':
      // Trigger fulfillment with full type safety
      triggerFulfillment(event as DepositReceivedV1);
      break;

    default:
      console.log('Unhandled event type:', event.event_type);
  }
}

async function sendPaymentConfirmation(event: PaymentSentV1) {
  // Your email logic here with full type safety
  console.log(`Sending confirmation for payment ${event.payment.nanoid}`);
  console.log(`Amount: ${event.payment.amount_cents} cents`);
  console.log(`Recipients: ${event.payment.recipients.length}`);
}

async function updateOrderStatus(event: PaymentGroupCreatedV1) {
  // Your database update logic here with full type safety
  console.log(`Updating payment group ${event.payment_group.nanoid} to processing`);
  console.log(`Payments count: ${event.payment_group.payments?.length || 0}`);
}

async function triggerFulfillment(event: DepositReceivedV1) {
  // Your fulfillment logic here with full type safety
  console.log(`Triggering fulfillment for deposit ${event.deposit.nanoid}`);
  console.log(`Amount: ${event.deposit.destination_amount_cents} cents`);
}

// JavaScript version (without TypeScript types)
function handleEvent(event) {
  switch (event.event_type) {
    case 'payment.sent':
      // Send confirmation email
      sendPaymentConfirmation(event);
      break;

    case 'payment.group.created':
      // Update order status
      updateOrderStatus(event);
      break;

    case 'deposit.received':
      // Trigger fulfillment
      triggerFulfillment(event);
      break;

    default:
      console.log('Unhandled event type:', event.event_type);
  }
}

async function sendPaymentConfirmation(event) {
  // Your email logic here
  console.log(`Sending confirmation for payment ${event.payment.nanoid}`);
}

async function updateOrderStatus(event) {
  // Your database update logic here
  console.log(`Updating payment group ${event.payment_group.nanoid} to processing`);
}

​
Common event types to start with

Here are the most commonly used Rise webhook events:

payment.sent

A payment has been successfully sent to the recipient

payment.group.created

A new payment group has been created with multiple payments

deposit.received

A deposit has been received and confirmed in your account

invite.accepted

A team member has accepted an invitation to join

​
Testing checklist

Before going live, verify that your webhook:

​
Monitor your webhook deliveries

Once your webhook is active, you can track its performance in the Rise app:
  1. Navigate to your webhook details page in the Rise app
  2. Click on “Delivery History” tab to see all webhook deliveries
  3. Monitor delivery success rates and response times
  4. Review failed deliveries to identify and fix issues
The delivery history shows:
  • Successful deliveries - Events delivered with 200 response
  • Failed deliveries - Events that couldn’t be delivered
  • Pending retries - Events waiting to be retried
  • Response details - HTTP status codes and response times

​
What’s next?

Congratulations! You now have a working webhook endpoint. Here’s what to explore next:

Explore Event Types

See the complete list of available events and their payloads

Security Best Practices

Learn about advanced security features and best practices

Webhook Management

Learn how to manage multiple webhooks and team configurations

Testing Tools

Testing your webhooks locally and troubleshooting common issues
Pro tip: Start with just one or two event types to keep things simple, then add more as your integration grows. It’s easier to debug and maintain fewer, well-configured webhooks.
SDK recommendation: Use the Rise SDK for webhook validation to get automatic type safety, proper error handling, and protection against common security issues. The SDK handles Buffer payloads, signature verification, and timestamp validation automatically.