Webhooks Overview

Chamelio webhooks let you subscribe to platform events and receive HTTP POST notifications to your endpoint as they happen - no polling required.

How Webhooks Work

You register a webhook endpoint URL in the Chamelio web application
When a subscribed event occurs, Chamelio sends an HTTP POST request to your URL with the event payload
Your server processes the payload and responds with a 2xx status code to acknowledge receipt

Registering a Webhook

Admins configure webhook endpoints in Settings > Developer > Webhooks in the Chamelio web application. You can:

Register multiple endpoint URLs
Subscribe each endpoint to specific event types
Edit, pause (or reactivate), or delete an endpoint from the ⋮ menu on its row

Authentication & Verification

Each webhook request includes a signature header so you can verify it came from Chamelio:

X-Chamelio-Signature: sha256=<hmac_hex_digest>

The signature is an HMAC-SHA256 digest of the raw request body, computed using your webhook secret. Verify it on your server before processing the payload:

import hmac
import hashlib

def verify_signature(payload_body: bytes, secret: str, signature_header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

const crypto = require('crypto');

function verifySignature(payloadBody, secret, signatureHeader) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payloadBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

Always verify the signature before processing a webhook payload. Skipping this step exposes your endpoint to spoofed requests.

Retry Policy

If your endpoint times out, returns 408, 429, or a 5xx status, or can’t be reached, Chamelio retries the delivery with a short backoff, up to 3 attempts in total. Other responses, such as other 4xx or 3xx statuses, aren’t retried. A delivery that still fails is recorded as failed.

Common Payload Fields

All webhook events share a common envelope:

{
  "event": "core.document.uploaded",
  "event_id": "3f7c1a8e-5b2d-4e9a-9c31-8a6f0d4b7e12",
  "organization_id": 42,
  "user_id": 1337,
  "payload_version": 1,
  "timestamp": "2026-09-02T14:32:00Z",
  "data": { ... }
}

Field	Type	Description
`event`	string	Event type identifier (for example `core.document.uploaded`)
`event_id`	string	UUID for this event delivery. Use it to deduplicate retries
`organization_id`	integer	ID of the organization in which the event occurred
`user_id`	integer or null	ID of the user who triggered the event. `null` when no user was responsible, such as a system action or a clickwrap accepted by one of your own end users
`payload_version`	integer	Envelope schema version. Currently `1` for every event
`timestamp`	string	ISO 8601 UTC timestamp of when the event was generated
`data`	object	Event-specific payload. See individual event pages for the schema

organization_id and user_id are integers, not prefixed strings. IDs inside data follow the same rule: document, task, and attachment identifiers are integers, while workflow identifiers are strings.

Available Events

Knowledge Center - Documents

Event	Description
`core.document.uploaded`	A new document was uploaded to Knowledge Center
`core.document.upload_with_issues`	A document was uploaded but processing encountered issues
`core.document.upload_completed`	A document upload finished processing successfully
`core.document.updated`	A document’s attributes or metadata were updated
`core.document.deleted`	A document was deleted from Knowledge Center

Flows - Workflows

Event	Description
`flows.workflow.new_version`	A new version of a workflow was published
`flows.workflow.deleted`	A workflow was deleted

Flows - Tasks

Event	Description
`flows.tasks.created`	A new workflow task was created
`flows.tasks.step_change`	A task moved to a different step
`flows.tasks.completed`	A task was completed
`flows.tasks.canceled`	A task was canceled
`flows.tasks.commented`	A comment was added to a task
`flows.tasks.new_negotiate_version`	A new negotiation version of a document was added to a task
`flows.tasks.new_attached_document`	One or more attachments were added to a task

Clickwrap

Event	Description
`clickwrap.accepted`	An end user accepted the active version of a clickwrap

Documents Vault

Event	Description
`vault.document.created`	A file was added to Documents Vault
`vault.document.updated`	A file was renamed, moved, or had its content replaced
`vault.document.deleted`	A file was deleted
`vault.folder.created`	A folder was created
`vault.folder.updated`	A folder was renamed or moved
`vault.folder.deleted`	A folder and everything in it was deleted

Overview

API Key Access

OAuth App Access

MCP (beta)

Webhooks

How Webhooks Work

Registering a Webhook

Authentication & Verification

Retry Policy

Common Payload Fields

Available Events

Knowledge Center - Documents

Flows - Workflows

Flows - Tasks

Clickwrap

Documents Vault

Overview

API Key Access

OAuth App Access

MCP (beta)

Webhooks

​How Webhooks Work

​Registering a Webhook

​Authentication & Verification

​Retry Policy

​Common Payload Fields

​Available Events

​Knowledge Center - Documents

​Flows - Workflows

​Flows - Tasks

​Clickwrap

​Documents Vault

How Webhooks Work

Registering a Webhook

Authentication & Verification

Retry Policy

Common Payload Fields

Available Events

Knowledge Center - Documents

Flows - Workflows

Flows - Tasks

Clickwrap

Documents Vault