​

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:

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

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

​

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
• Build notification systems based on user actions

​

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.