Webhook Quick Start

Set up your first Rise webhook in under 10 minutes

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

Express.js

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:

Node.js with 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:

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.