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

# Webhook Events

> Comprehensive guide to all webhook events provided by ContactManager, including payload structures and examples for each event type

# Webhook Events

ContactManager provides webhook events to notify your application about different user activities. Each webhook payload includes an event type and relevant data about that event.

## Common Payload Structure

All webhook payloads follow this standard structure:

```json theme={null}
{
  "id": "uuid",
  "event": "event.name",
  "payload": {
    // Event-specific data
  }
}
```

* **id**: A unique identifier for this webhook delivery (useful for deduplication)
* **event**: The type of event that occurred
* **payload**: Contains all relevant data about the event

## Available Events

### User Events

#### `user.new`

Triggered when a new user is created in your system.

```json theme={null}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "event": "user.new",
  "payload": {
    "organization_id": "uuid",
    "user_id": "uuid",
    "email": "user@example.com",
    "phone": "+14155552671",
    "full_name": "John Doe"
  }
}
```

#### `user.is_contact`

Triggered when a newly joined user potentially knows existing users in your system. This helps identify possible connections between users based on contact information matching.

```json theme={null}
{
  "id": "123e4567-e89b-12d3-a456-426614174001",
  "event": "user.is_contact",
  "payload": {
    "organization_id": "uuid",
    "user_id": "uuid",
    "email": "user@example.com",
    "phone": "+14155552671",
    "matched_user_ids": ["uuid", "uuid"]
  }
}
```

The `matched_user_ids` array contains IDs of existing users who might know the new user. You can use this to suggest connections or build social features that connect users who likely know each other.

#### `user.deleted`

Triggered when a user is deleted from your organization.

```json theme={null}
{
  "id": "123e4567-e89b-12d3-a456-426614174007",
  "event": "user.deleted",
  "payload": {
    "organization_id": "uuid",
    "user_id": "uuid",
    "email": "user@example.com",
    "phone": "+14155552671"
  }
}
```

This event is useful for keeping external systems in sync with your ContactManager data and for compliance with data deletion regulations.

### Social Events

#### `user.follow`

Triggered when a user follows another user.

```json theme={null}
{
  "id": "123e4567-e89b-12d3-a456-426614174002",
  "event": "user.follow",
  "payload": {
    "organization_id": "uuid",
    "follower_id": "uuid",
    "followed_id": "uuid",
    "follower_name": "John Doe",
    "followed_name": "Jane Smith"
  }
}
```

#### `user.unfollow`

Triggered when a user unfollows another user.

```json theme={null}
{
  "id": "123e4567-e89b-12d3-a456-426614174003",
  "event": "user.unfollow",
  "payload": {
    "organization_id": "uuid",
    "follower_id": "uuid",
    "followed_id": "uuid",
    "follower_name": "John Doe",
    "followed_name": "Jane Smith"
  }
}
```

### Event Management

#### `user.create_event`

Triggered when a user creates a new event.

```json theme={null}
{
  "id": "123e4567-e89b-12d3-a456-426614174004",
  "event": "user.create_event",
  "payload": {
    "organization_id": "uuid",
    "event_id": "uuid",
    "user_id": "uuid",
    "title": "Product Launch",
    "event_type": "launch",
    "description": "Launching our new product line",
    "is_public": true,
    "start_time": "2023-05-15T15:00:00Z",
    "end_time": "2023-05-15T17:00:00Z"
  }
}
```

#### `user.update_event`

Triggered when a user updates an existing event.

```json theme={null}
{
  "id": "123e4567-e89b-12d3-a456-426614174005",
  "event": "user.update_event",
  "payload": {
    "organization_id": "uuid",
    "event_id": "uuid",
    "user_id": "uuid",
    "title": "Updated: Product Launch",
    "event_type": "launch",
    "description": "Launching our new product line with exclusive preview",
    "is_public": true,
    "start_time": "2023-05-15T16:00:00Z",
    "end_time": "2023-05-15T18:00:00Z"
  }
}
```

#### `user.delete_event`

Triggered when a user deletes an event.

```json theme={null}
{
  "id": "123e4567-e89b-12d3-a456-426614174006",
  "event": "user.delete_event",
  "payload": {
    "organization_id": "uuid",
    "event_id": "uuid",
    "user_id": "uuid"
  }
}
```

### Reaction Events

#### `user.create_reaction`

Triggered when a user adds a reaction to an event. Reactions include likes, loves, support, and other emotion types.

```json theme={null}
{
  "id": "123e4567-e89b-12d3-a456-426614174008",
  "event": "user.create_reaction",
  "payload": {
    "organization_id": "uuid",
    "event_id": "uuid",
    "reaction_id": "uuid",
    "user_id": "uuid",
    "reaction_type": "like",
    "metadata": {}
  }
}
```

The `reaction_type` can be predefined types like "like", "love", "super\_like", "support", "laugh", "wow", "sad", "angry", or custom strings for extended functionality.

#### `user.update_reaction`

Triggered when a user changes their existing reaction to an event.

```json theme={null}
{
  "id": "123e4567-e89b-12d3-a456-426614174009",
  "event": "user.update_reaction",
  "payload": {
    "organization_id": "uuid",
    "event_id": "uuid",
    "reaction_id": "uuid",
    "user_id": "uuid",
    "reaction_type": "love",
    "metadata": {}
  }
}
```

This event occurs when a user had previously reacted to an event and changes their reaction to a different type.

#### `user.delete_reaction`

Triggered when a user removes their reaction from an event.

```json theme={null}
{
  "id": "123e4567-e89b-12d3-a456-426614174010",
  "event": "user.delete_reaction",
  "payload": {
    "organization_id": "uuid",
    "event_id": "uuid",
    "reaction_id": "uuid",
    "user_id": "uuid",
    "reaction_type": "like"
  }
}
```

Use this event to update reaction counters, activity feeds, or notification systems when users unreact to content.

## Using Events for Social Features

ContactManager's webhook events are designed to help you build powerful social features:

* Use `user.is_contact` to identify potential connections between users
* Track follow/unfollow actions to build social graphs
* Monitor user events to create activity feeds and social timelines
* Track reactions to build engagement systems and real-time interaction feeds
* Build notification systems based on user actions and reactions

## Event Delivery and Reliability

To ensure reliable delivery of events, ContactManager implements a robust retry mechanism:

* Events are delivered in real-time when they occur
* If your endpoint is unavailable or returns an error, we retry automatically
* Retry attempts are made at 3 and 10 seconds after the initial failure
* All delivery attempts are logged with their status, duration, and response information
* Each event has a unique ID to help with deduplication in your system

For implementation details, see our [implementation guides](/webhooks/implementation).