Webhooks

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

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

{
  "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:

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

{
  "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.

Respond quickly with 200 OK and process the event asynchronously. A slow handler increases the chance of timeouts and retries.

Managing Webhooks

# List webhooks
GET /v1/webhooks

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

# Delete a webhook
DELETE /v1/webhooks/wh_01HXYZWH1

Getting Started

Platform Concepts

App Guides — Office

App Guides — Access

App Guides — Sales

App Guides — Careers

App Guides — Project

App Guides — Guard

Integrations

Security & Compliance

Creating a Webhook

Verifying Payloads

Payload Format

Retries and Delivery Guarantees

Managing Webhooks

​Creating a Webhook

​Verifying Payloads

​Payload Format

​Retries and Delivery Guarantees

​Managing Webhooks

Creating a Webhook

Verifying Payloads

Payload Format

Retries and Delivery Guarantees

Managing Webhooks