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

# Events

> Understand Essal's async event system — how app-level events are produced, routed, and consumed via webhooks.

Essal has a built-in event bus that publishes real-time events whenever significant actions occur across any of the six apps. Your integration can subscribe to these events via **webhooks** to react to platform activity without polling.

## Event Structure

Every event follows a consistent envelope format:

```json theme={null}
{
  "id": "evt_01HXYZEVT1",
  "type": "office.document.created",
  "workspace_id": "ws_01HXYZABC",
  "timestamp": "2026-07-10T13:45:00Z",
  "actor": {
    "type": "user",
    "id": "usr_01HXYZ1234"
  },
  "payload": {
    "document_id": "doc_01HXYZABC",
    "title": "Q3 Planning Draft",
    "owner_id": "usr_01HXYZ1234"
  }
}
```

## Event Catalog

### Office Events

| Event Type                | Trigger                                  |
| ------------------------- | ---------------------------------------- |
| `office.document.created` | A new document is created                |
| `office.document.updated` | A document's content or metadata changes |
| `office.document.deleted` | A document is deleted                    |
| `office.file.uploaded`    | A file is uploaded to storage            |

### Access Events

| Event Type                | Trigger                       |
| ------------------------- | ----------------------------- |
| `access.user.created`     | A new user is provisioned     |
| `access.user.deactivated` | A user account is deactivated |
| `access.session.revoked`  | An active session is revoked  |

### Sales Events

| Event Type                 | Trigger                              |
| -------------------------- | ------------------------------------ |
| `sales.deal.stage_changed` | A deal moves to a new pipeline stage |
| `sales.contact.created`    | A new contact is added               |
| `sales.deal.won`           | A deal is marked as won              |
| `sales.deal.lost`          | A deal is marked as lost             |

### Careers Events

| Event Type                          | Trigger                                  |
| ----------------------------------- | ---------------------------------------- |
| `careers.application.submitted`     | A candidate submits an application       |
| `careers.application.stage_changed` | An applicant moves to a new hiring stage |
| `careers.job.published`             | A job posting goes live                  |

### Project Events

| Event Type                 | Trigger                   |
| -------------------------- | ------------------------- |
| `project.task.created`     | A new task is created     |
| `project.task.completed`   | A task is marked complete |
| `project.project.archived` | A project is archived     |

### Guard Events

| Event Type              | Trigger                          |
| ----------------------- | -------------------------------- |
| `guard.alert.triggered` | A threat detection rule fires    |
| `guard.policy.updated`  | An access policy is modified     |
| `guard.audit.exported`  | An audit log export is completed |

## Subscribing to Events

Create a webhook subscription to receive events at your endpoint:

```bash theme={null}
POST /v1/webhooks
{
  "url": "https://hooks.example.com/essal",
  "events": ["sales.deal.won", "careers.application.submitted"],
  "secret": "whs_live_xxxxxxxxxxxxxx"
}
```

<Note>
  Essal signs every webhook payload with an HMAC-SHA256 signature using your webhook secret. Always verify the `X-Essal-Signature` header before processing events.
</Note>

## Delivery and Retry

Events are delivered with **at-least-once** guarantees. If your endpoint returns a non-2xx response, Essal will retry up to 5 times using exponential backoff over 24 hours. After all retries are exhausted, the event is marked as failed and available for manual replay in the dashboard.