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

# Webhooks

Webhooks are a way to receive real-time updates from Clasp. They allow your application to be notified automatically when certain events occur in Clasp, eliminating the need to continuously poll the API for changes.

## Overview

When an important change happens in your Clasp account (like a member being updated or an employer being created), Clasp generates an event and sends an HTTP POST request to your configured endpoint with details about what changed. Please reach out to Clasp to get started.

## Event Payload

Each event is sent as a JSON payload with the following structure:

```json theme={null}
{
  "id": "evnt_8Ln4MbSf5uLFurmAOfNr9",
  "event_type": "updated",
  "object_id": "er_67Al5UIOFMPsrHbLI8YnU", 
  "object_type": "employer",
  "employer": "er_67Al5UIOFMPsrHbLI8YnU",
  "created_at": "2025-01-06T05:41:19.093833Z"
}
```

### Field Descriptions

* `id`: Unique identifier for the event
* `event_type`: The type of change that occurred
* `object_id`: Identifier of the object that changed
* `object_type`: Type of object that changed
* `employer`: Identifier of the employer the object belongs to
* `created_at`: Timestamp when the event occurred

### Supported Events

| Object Types               | Event Types |
| -------------------------- | ----------- |
| - `member`                 | - `created` |
| - `dependent`              | - `updated` |
| - `employer`               | - `deleted` |
| - `payroll_benefit`        |             |
| - `open_enrollment_window` |             |
| - `enrollment`             |             |
| - `business_unit`          |             |

## Security

### Verifying Webhook Signatures

Every webhook request includes two important headers:

1. `Clasp-Event-Timestamp`: When the event was sent
2. `Clasp-Event-Signature`: HMAC signature of the event

To verify the event is legitimate via the signature:

1. Concatenate the event payload with the timestamp: `${payload}.${timestamp}`
2. Create an HMAC SHA-256 digest with the shared secret
3. Compare the calculated signature with `Clasp-Event-Signature`

Here's a Python example of signature verification:

```python theme={null}
import hashlib
import hmac
import json

def verify_event(payload, timestamp, signature, secret):
    # Calculate expected signature
    message = f"{json.dumps(payload)}.{timestamp}".encode("utf-8")
    expected = hmac.new(
        secret.encode('utf-8'),
        message,
        hashlib.sha256
    ).hexdigest()
    
    # Compare the digests
    return hmac.compare_digest(expected, signature)
```

## Best Practices

### 1. Response

* Return a 200 status code as quickly as possible
* Store the event ID to prevent duplicate processing
* New event and object types will be added over time. Ensure a 200 response is returned for all events
* Clasp will retry failed event deliveries up to 10 times when an error response is returned

### 2. Fetching Current Data

* Use the `object_type` and `object_id` to determine which API endpoint to query
* Fetch the current state from the API