> ## Documentation Index
> Fetch the complete documentation index at: https://docs.riseworks.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Event Types Overview

> Complete reference of all available events and their data structures

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:

<CodeGroup>
  ```json Example Event Structure theme={null}
  {
    "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
  }
  ```
</CodeGroup>

<CardGroup cols={2}>
  <Card title="Envelope Fields" icon="envelope">
    Consistent metadata present in all events for tracking and processing
  </Card>

  <Card title="Event Payload" icon="code">
    Event-specific data that varies by event type and contains the actual business data
  </Card>
</CardGroup>

### Envelope field reference

<ParamField path="object" type="string" required>
  The type of object this webhook represents (always "event")
</ParamField>

<ParamField path="created" type="number" required>
  The Unix timestamp when the event was created
</ParamField>

<ParamField path="event_type" type="string" required>
  The type of event (e.g., `payment.sent`)
</ParamField>

<ParamField path="event_version" type="string" required>
  Schema version for the event — see [Event versions](#event-versions)
</ParamField>

<ParamField path="request_id" type="string">
  Request tracking identifier
</ParamField>

<ParamField path="idempotency_key" type="string" required>
  Key to prevent duplicate processing
</ParamField>

### 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` |

<Note>
  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.
</Note>

<Warning>
  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](/webhooks/reference/migration).
</Warning>

### Data types and formats

Rise webhooks use consistent data types across all events:

<Tabs>
  <Tab title="String 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...`)
  </Tab>

  <Tab title="Numeric Formats">
    * **Amounts** - Large integers as strings to avoid precision loss
    * **Cents** - Integer values for fiat currency amounts
    * **Decimals** - Integer values for token decimal places
  </Tab>
</Tabs>

<Warning>
  **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.
</Warning>

## Complete event example

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

<CodeGroup>
  ```json Complete Webhook Event theme={null}
  {
    "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"
      }
    }
  }
  ```
</CodeGroup>

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:

<CardGroup cols={2}>
  <Card title="Payment Events" icon="credit-card" href="/webhooks/events/payment">
    Events related to payment processing, including payment group creation and individual payment completion
  </Card>

  <Card title="Deposit Events" icon="coins" href="/webhooks/events/deposit">
    Events triggered when funds are deposited into company accounts from external sources
  </Card>

  <Card title="Invite Events" icon="users" href="/webhooks/events/invite">
    Events covering the full invitation lifecycle — acceptance, rejection, and expiry
  </Card>

  <Card title="Security Events" icon="shield" href="/webhooks/events/security">
    Events related to account security, fraud detection, and compliance monitoring
  </Card>
</CardGroup>

***

## Quick Reference

<AccordionGroup>
  <Accordion title="Payment Events" icon="credit-card">
    * **payment.group.created** - Payment group created with multiple payments
    * **payment.sent** - Individual payment processed and sent
  </Accordion>

  <Accordion title="Deposit Events" icon="coins">
    * **deposit.received** - Funds deposited to company account
  </Accordion>

  <Accordion title="Invite Events" icon="users">
    * **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
  </Accordion>

  <Accordion title="Security Events" icon="shield">
    * **withdraw\_account.duplicated\_detected** - Duplicate withdrawal account detected
  </Accordion>
</AccordionGroup>

***

## Implementation Tips

<Info>
  **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.
</Info>

<Tip>
  **Getting started**: If you're building a payment integration, start with [Payment Events](/webhooks/events/payment). For wallet funding notifications, check [Deposit Events](/webhooks/events/deposit).
</Tip>