# Event Types

Complete list of webhook events available in iClosed.io and their payload structures.

## Available Webhook Events

iClosed.io provides a comprehensive set of webhook events that allow you to stay informed about important changes in your account. Each event type has a unique identifier and includes relevant data in the payload.

## Event Categories

### Contact Events

| Event ID | Description |
|  --- | --- |
| `newContactCreated` | Triggered when a new contact is created |
| `contactDetailChanged` | Triggered when contact information is updated |
| `contactByStatus` | Triggered when a contact’s status changes (for example after a call is booked); `hookType` is `"contactByStatus"` |


### Call Events

| Event ID | Description |
|  --- | --- |
| `newCallScheduled` | Triggered when a new call is scheduled |
| `callCancelled` | Triggered when a call is cancelled |
| `callRescheduled` | Triggered when a call is rescheduled |


### Call Outcome Events

| Event ID | Description |
|  --- | --- |
| `callOutcome` | Triggered when a call outcome is added |


## Event Payload Structure

Each webhook event type has its own specific payload structure. The HTTP body is a **single JSON object** (not a JSON array wrapper).

```json
{
  "hookType": "Event type description"
}
```

## Available Event Types

### Contact Created (`newContactCreated`)

Triggered when a new contact is created in your iClosed.io account through any channel (form submission, manual creation, API, etc.).

- **Payload Structure:** Complete contact object including personal details, event information, tracking data, questions and answers, and any associated calls.
- **Key Fields:** Contact ID, name, email, phone, status, event details, tracking parameters, form responses, and call information.
- **Use Cases:** CRM synchronization, lead tracking, customer onboarding workflows, marketing attribution.


### Contact Updated (`contactDetailChanged`)

Triggered when an existing contact's information is modified in your iClosed.io account.

- **Payload Structure:** Complete updated contact object with `updatedAttributes` field showing what specifically changed, plus all current contact data.
- **Key Fields:** All contact fields plus `updatedAttributes` array, `updatedAt` timestamp, and `hookType` set to `"Contact updated"`.
- **Use Cases:** CRM updates, data validation, audit trails, workflow triggers, analytics tracking.


### Contact by status (`contactByStatus`)

Triggered when a contact’s **status** changes in a way your workspace tracks for webhooks (for example when they move into a call-booked state). The payload is the same general **contact** shape as other contact webhooks, including `latestCall` when a call is associated, plus `updatedAttributes` describing what changed.

- **Payload Structure:** Contact object with `status`, `questionsAndAnswers`, `event`, `tracking`, optional `latestCall`, and `dataIntelligence` blocks.
- **Key Fields:** `status`, `updatedAttributes`, `hookType` set to `"contactByStatus"`, and when present `latestCall` for the scheduled call tied to the transition.
- **Use Cases:** CRM stage automation, routing by pipeline status, alerting when a lead books a strategy call.


### Call Booked (`newCallScheduled`)

Triggered when a call is successfully scheduled and booked in your iClosed.io account.

- **Payload Structure:** Event type configuration, call instance details, invitee information, scheduling data, and tracking information.
- **Key Fields:** Event type details, call UUID, assigned team member, start/end times, invitee details, booking form responses, and tracking data.
- **Use Cases:** Calendar synchronization, team notifications, CRM integration, analytics tracking, workflow automation.


### Call Cancelled (`callCancelled`)

Triggered when a previously booked call is cancelled by either the invitee or the host.

- **Payload Structure:** Complete call information with cancellation details, who cancelled, when, and the reason for cancellation.
- **Key Fields:** `event.canceled: true` plus cancellation metadata (`canceler_name`, `cancel_reason`, `canceled_at`); `invitee` may still carry cancellation fields with mixed `canceled` flags—inspect the sample payload for your integration.
- **Use Cases:** Calendar management, team notifications, CRM updates, follow-up automation, resource management.


### Call Rescheduled (`callRescheduled`)

Triggered when a call is rescheduled to a new time in your iClosed.io account.

- **Payload Structure:** Call information with new timing, original timing (`old_start_time`), and rescheduling details.
- **Key Fields:** All call details plus `old_start_time`, `is_reschedule: true`, and `reschedule_reason` (if provided).
- **Use Cases:** Calendar updates, team notifications, customer communication, resource management, workflow adjustments.


### Outcome Added (`callOutcome`)

Triggered when a call outcome is recorded after a call is completed in your iClosed.io account.

- **Payload Structure:** Complete call outcome data including contact information, call details, outcome type, deal information, and transaction details.
- **Key Fields:** Call UUID, contact details, `callOutcome` type, deal value, product name, transaction details, and outcome notes.
- **Use Cases:** Sales tracking, CRM updates, commission calculations, analytics, lead scoring updates, follow-up automation.


## Detailed Documentation

For comprehensive information about each webhook event type, including complete payload examples, field descriptions, and implementation details, see the individual documentation pages:

- **Contact Created** – Complete guide to contact creation events
- **Contact Updated** – Detailed contact update event documentation
- **Call Booked** – Comprehensive call booking event guide
- **Call Cancelled** – Complete call cancellation event documentation
- **Call Rescheduled** – Detailed call rescheduling event guide
- **Outcome Added** – Comprehensive call outcome event documentation


Each detailed page includes:

- Complete JSON payload examples
- Field-by-field explanations
- Use cases and best practices
- Response requirements
- Implementation guidelines


## Subscribing to Events

When creating a webhook, specify which events you want to receive by including their IDs and names in the `triggers` array:

```json
{
  "url": "https://your-app.com/webhooks",
  "isActive": true,
  "triggers": [
    {
      "id": "newContactCreated",
      "name": "Contact created"
    },
    {
      "id": "contactByStatus",
      "name": "Contact by status"
    },
    {
      "id": "newCallScheduled",
      "name": "Call booked"
    },
    {
      "id": "callOutcome",
      "name": "Outcome added"
    }
  ]
}
```

### Valid Trigger Combinations

| Trigger ID | Trigger Name |
|  --- | --- |
| `newContactCreated` | Contact created |
| `contactDetailChanged` | Contact updated |
| `contactByStatus` | Contact by status |
| `newCallScheduled` | Call booked |
| `callCancelled` | Call cancelled |
| `callOutcome` | Outcome added |
| `callRescheduled` | Call rescheduled |


## Event Reliability

- **Real-time Delivery:** Events are delivered immediately when they occur
- **Retry Logic:** Failed deliveries are retried with exponential backoff
- **Duplicate Handling:** Your endpoint should handle potential duplicate events
- **Response Time:** Respond with `2xx` status codes within 5 seconds


## Best Practices

1. **Idempotency** – Design your webhook handlers to handle duplicate events safely
2. **Quick Response** – Respond with `2xx` status codes within 5 seconds to avoid retries
3. **Error Handling** – Log failed events for debugging and monitoring
4. **Data Validation** – Always validate the webhook payload structure
5. **Rate Limiting** – Be prepared for high event volumes during peak times
6. **Monitoring** – Set up alerts for webhook failures and response times
7. **Testing** – Test your webhook endpoints with sample payloads before going live


## Getting Started

1. **Choose Events** – Select the events you want to receive based on your use case
2. **Create Webhook** – Use the webhook management API to create your subscription
3. **Implement Handler** – Build your webhook endpoint to process the events
4. **Test** – Verify your implementation with test events
5. **Monitor** – Set up monitoring and alerting for your webhook performance