> ## 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.

# Webhooks

> Set up and manage webhook subscriptions to receive real-time events from the Essal platform.

Webhooks allow your application to receive HTTP notifications in real time whenever events occur across the Essal suite. Instead of polling the API, you register an endpoint and Essal pushes event payloads to it automatically.

## Creating a Webhook

```bash theme={null}
POST /v1/webhooks
{
  "url": "https://hooks.example.com/essal",
  "events": [
    "office.document.created",
    "sales.deal.won",
    "careers.application.submitted",
    "guard.alert.triggered"
  ],
  "description": "Main integration endpoint"
}
```

**Response**

```json theme={null}
{
  "id": "wh_01HXYZWH1",
  "url": "https://hooks.example.com/essal",
  "secret": "whs_live_xxxxxxxxxxxxxx",
  "status": "active",
  "created_at": "2026-07-10T09:00:00Z"
}
```

Copy the `secret` immediately — it is only shown at creation time.

## Verifying Payloads

Every webhook delivery includes an `X-Essal-Signature` header. Verify it to ensure the request is genuine:

```js theme={null}
import crypto from "crypto";

function verifySignature(payload, signature, secret) {
  const hmac = crypto.createHmac("sha256", secret);
  hmac.update(payload);
  const expected = "sha256=" + hmac.digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}
```

Always use `timingSafeEqual` to prevent timing attacks.

## Payload Format

```json theme={null}
{
  "id": "evt_01HXYZEVT1",
  "type": "sales.deal.won",
  "workspace_id": "ws_01HXYZABC",
  "timestamp": "2026-07-10T15:00:00Z",
  "actor": { "type": "user", "id": "usr_01HXYZ5678" },
  "payload": {
    "deal_id": "deal_01HXYZAAA",
    "title": "Acme Corp — Enterprise Licence",
    "value": 72000
  }
}
```

## Retries and Delivery Guarantees

Essal delivers events with **at-least-once** guarantees. If your endpoint returns a non-2xx response or times out (10-second limit), Essal retries up to **5 times** with exponential backoff over 24 hours.

Make your webhook handler **idempotent** using the `evt.id` field to deduplicate retried deliveries.

<Tip>
  Respond quickly with `200 OK` and process the event asynchronously. A slow handler increases the chance of timeouts and retries.
</Tip>

## Managing Webhooks

```bash theme={null}
# List webhooks
GET /v1/webhooks

# Pause a webhook
PATCH /v1/webhooks/wh_01HXYZWH1 { "status": "paused" }

# Delete a webhook
DELETE /v1/webhooks/wh_01HXYZWH1
```