Event Types Overview

Understanding webhook event payloads is crucial for building robust integrations with Rise. This guide provides comprehensive documentation for all event types, their data structures, and field specifications.

Understanding event payloads

Every webhook event follows a consistent structure with three main components:

Event envelope

All webhook events are wrapped in a standard envelope:

{
  "object": "event",
  "created": 1751590453,
  "request_id": "req-1751590452487",
  "event_type": "payment.sent",
  "event_version": "2.0",
  "idempotency_key": "85420805-0b5e-4b11-b7f4-c6f05db7120b",
  // Event-specific data goes here
}

Envelope Fields

Consistent metadata present in all events for tracking and processing

Event Payload

Event-specific data that varies by event type and contains the actual business data

Envelope field reference

string

required

The type of object this webhook represents (always “event”)

number

required

The Unix timestamp when the event was created

string

required

The type of event (e.g., payment.sent)

string

required

Schema version for the event — see Event versions

string

Request tracking identifier

string

required

Key to prevent duplicate processing

Event versions

event_version is the version of that event’s payload schema. Each event type is versioned independently, so two events delivered to the same endpoint can be on different versions. Versions start at 2.0, not 1.0. Version 1.0 belongs to the legacy v1 webhooks, whose payloads have a different shape and signing scheme entirely. To keep the two from being confused, every event on the current v2 webhooks starts at 2.0 — including events introduced long after v2 shipped, such as invite.expired and invite.rejected. A 2.0 therefore does not mean an event has been revised once; it means it is the first version of that event on v2. From there, an event’s version moves independently as its payload changes:

Change	Version	Example
First version of an event on v2 webhooks	`2.0`	`invite.expired`
Additive change (new optional field)	`2.0` → `2.1`	—
Breaking change (field removed, renamed, or retyped)	`2.x` → `3.0`	`withdraw_account.duplicated_detected`

Always branch on event_type and event_version when you handle an event. A new version of an event you already consume can change the payload, and reading event_version is how you notice.

If you are receiving "event_version": "1.0", you are on a legacy v1 webhook endpoint, not a v2 one. The payload shape you receive is the legacy one, and the new events documented here are not delivered to it. See the migration guide.

Data types and formats

Rise webhooks use consistent data types across all events:

String Formats
Numeric Formats

Nanoids - 15-character identifiers with prefixes (e.g., co-abc123def456789)
ISO-8601 timestamps - UTC timestamps (e.g., 2024-01-15T10:30:00.000Z)
Email addresses - Valid email format
Currency codes - 3-letter ISO codes (e.g., USD, EUR)
Blockchain addresses - 42-character hex addresses (e.g., 0x1234...)

Important: All monetary amounts in blockchain context are transmitted as strings to prevent JSON number precision issues. Fiat amounts are typically in cents as integers.

Complete event example

Here’s how a complete webhook event looks when delivered to your endpoint:

{
  "object": "event",
  "created": 1751590453,
  "request_id": "req-1751590452487",
  "event_type": "payment.sent",
  "event_version": "2.0",
  "idempotency_key": "85420805-0b5e-4b11-b7f4-c6f05db7120b",
  "payment": {
    "nanoid": "pa-xyz789abc123456",
    "onchain_id": "67890",
    "group_onchain_id": "12345",
    "invoice_nanoid": "iv-def456ghi789012",
    "creation_transaction": "tx-abc123def456789",
    "process_transaction": "tx-def456ghi789012",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:35:00.000Z",
    "pay_at_time": "1705312200",
    "pay_type": "1",
    "token": {
      "address": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
      "name": "USD Coin",
      "symbol": "USDC",
      "decimals": 6
    },
    "recipients": [
      {
        "nanoid": "pa-xyz789abc123456",
        "email": "contractor@example.com",
        "name": "John Doe",
        "entity_type": "user"
      }
    ],
    "amount": "1000000000",
    "amount_cents": 100000,
    "invoice_type": "time_entry",
    "invoice_description": "Development work for Q1 2024",
    "role_description": "Senior Frontend Developer",
    "currency": "USD",
    "payment_group": {
      "nanoid": "pg-abc123def456789",
      "onchain_id": "12345",
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z"
    }
  }
}

This example shows the complete structure with envelope fields at the top level and event-specific data flattened into the root object.

Event Categories

Rise webhooks are organized into the following categories based on their purpose and context:

Payment Events

Events related to payment processing, including payment group creation and individual payment completion

Deposit Events

Events triggered when funds are deposited into company accounts from external sources

Invite Events

Events covering the full invitation lifecycle — acceptance, rejection, and expiry

Security Events

Events related to account security, fraud detection, and compliance monitoring

Quick Reference

Payment Events

payment.group.created - Payment group created with multiple payments
payment.sent - Individual payment processed and sent

Deposit Events

deposit.received - Funds deposited to company account

Invite Events

invite.accepted - Team member invitation accepted
invite.rejected - Team member invitation declined by the invitee
invite.expired - Team member invitation lapsed after 90 days without a response

Security Events

withdraw_account.duplicated_detected - Duplicate withdrawal account detected

Implementation Tips

Field reference tip: Each event category page contains complete field documentation and payload examples. Bookmark the relevant category pages for quick reference while building your webhook handlers.

Getting started: If you’re building a payment integration, start with Payment Events. For wallet funding notifications, check Deposit Events.

Getting Started

Implementation

Operations

Reference

Webhook Payloads

Understanding event payloads

Event envelope

Envelope Fields

Event Payload

Envelope field reference

Event versions

Data types and formats

Complete event example

Event Categories

Payment Events

Deposit Events

Invite Events

Security Events

Quick Reference

Implementation Tips

​Understanding event payloads

​Event envelope

Envelope Fields

Event Payload

​Envelope field reference

​Event versions

​Data types and formats

​Complete event example

​Event Categories

Payment Events

Deposit Events

Invite Events

Security Events

​Quick Reference

​Implementation Tips

Understanding event payloads

Event envelope

Envelope field reference

Event versions

Data types and formats

Complete event example

Event Categories

Quick Reference

Implementation Tips