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

# Get Started With Webhooks & Events

> Use incoming webhook events to get real-time updates

**Listen for events on your Lucca account so your integration can automatically react in near real-time.**

```mermaid theme={null}
sequenceDiagram
    box You
    participant Webhook-Endpoint
    actor User
    end

    box Lucca
    participant Lucca API
    end

    User->>+Lucca API: POST /lucca-api/employees
    destroy User
    Lucca API-->>-User: 201 Created

    Lucca API->>Lucca API: POST /lucca-api/events<br/>"employee.created"
    Lucca API->>Webhook-Endpoint: POST https://yourdomain.com/{webhook-endpoint}<br/>"employee.created"
    
    alt is success
    Webhook-Endpoint-->>Lucca API: 202 Accepted
    Webhook-Endpoint->>Webhook-Endpoint: Handle event
    else is retry later
    Webhook-Endpoint-->>Lucca API: 503 Service unavailable<br/>429 Too Many Requests
    Lucca API->>Lucca API: Plan retry later
    end
```

## Why Should You Use Webhooks?

Webhooks offer some advantages compared to regular polling:

* polling to the REST API is often inefficient;
* polling may result in timing conflicts;
* webhooks reduce the delay between the moment a change occurs and the moment your integration reacts;
* webhooks reduces the number of HTTP request, and as such reduce the risk of exceeding our [rate-limit](../limits)

## Events Overview

Most of the resources in the Lucca API are subject to events. This means whenever their state changes,
an `event` object is created and can be sent to your webhook-endpoint.

Please note that a single change in the API may result in the creation of several events, for example,
creating a new employee results in the creation of:

* an `employee.created` event (this is what triggered this chain reaction) ;
* an `employment.created` event (an employee must have at least one employment, which is created along the employee) ;
* a `job-position.created` event (for the same reasons).

By registering your webhook endpoints in your Lucca account, these events can be automatically sent to
you through HTTP POST requests.

<Note>Please note that an event is only created when the intrinsic attributes of a resource change. As
a result, changing an employee's given name will not trigger a `leave.updated` event even if the employee
representation might be [embedded](../using-api/includes) into the leave representation.</Note>

## At-least-once Guarantee

Regarding event delivery, there is only one guarantee: each event will be delivered **at-least-once** to
your webhook endpoint.

This means:

* **an event may be delivered several times**, due to the retry feature, and as such, you should consider
  **idempotency** when handling them.
* **there is no guarantee regarding the order of events**: you may receive an "update" event for a resource
  whose "created" event will arrive later. You should use the `occurredAt` UTC timestamp attribute of events
  in order to reorder them.