Webhook Quick Start

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:

Navigate to webhooks

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

Create new webhook

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

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)

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

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:

Access test feature

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

Select event type

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

Send test event

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

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:

Functionality checks

Responds with a 200 status code within 10 seconds
Handles all the event types you’ve subscribed to
Processes events idempotently (handles duplicates gracefully)
Logs events for debugging

Security checks

Verifies webhook signatures correctly (use Rise SDK for best results)
Rejects invalid signatures properly
Validates timestamps to prevent replay attacks
Uses HTTPS for production (recommended)
Handles Buffer payloads correctly for signature verification

Error handling

Handles unknown event types gracefully
Doesn’t crash on malformed payloads
Has proper error logging and monitoring

Monitor your webhook deliveries

Once your webhook is active, you can track its performance in the Rise app:

Navigate to your webhook details page in the Rise app
Click on “Delivery History” tab to see all webhook deliveries
Monitor delivery success rates and response times
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.

Getting Started

Implementation

Operations

Reference

Webhook Payloads

Prerequisites

Rise Account

Server Setup

HTTPS Recommended

API Credentials

Step 1: Create your webhook endpoint

Step 2: Register your webhook in the Rise app

Step 3: Test your webhook

Step 4: Add signature verification with Rise SDK

Installing the Rise SDK

Step 5: Handle events in your application

Common event types to start with

payment.sent

payment.group.created

deposit.received

invite.accepted

Testing checklist

Monitor your webhook deliveries

What’s next?

Explore Event Types

Security Best Practices

Webhook Management

Testing Tools

Getting Started

Implementation

Operations

Reference

Webhook Payloads

​Prerequisites

Rise Account

Server Setup

HTTPS Recommended

API Credentials

​Step 1: Create your webhook endpoint

​Step 2: Register your webhook in the Rise app

​Step 3: Test your webhook

​Step 4: Add signature verification with Rise SDK

​Installing the Rise SDK

​Step 5: Handle events in your application

​Common event types to start with

payment.sent

payment.group.created

deposit.received

invite.accepted

​Testing checklist

​Monitor your webhook deliveries

​What’s next?

Explore Event Types

Security Best Practices

Webhook Management

Testing Tools

Prerequisites

Step 1: Create your webhook endpoint

Step 2: Register your webhook in the Rise app

Step 3: Test your webhook

Step 4: Add signature verification with Rise SDK

Installing the Rise SDK

Step 5: Handle events in your application

Common event types to start with

Testing checklist

Monitor your webhook deliveries

What’s next?