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

Configure webhook endpoints in Settings → Integrations → Webhooks in the Chamelio web application. You can:

Register multiple endpoint URLs
Subscribe each endpoint to specific event types
View delivery logs and retry failed deliveries

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 does not respond with a 2xx status within 10 seconds, Chamelio will retry delivery with exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours

After 4 failed retries the event is marked as undelivered. You can manually replay events from the webhook delivery log in the Chamelio web application.

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

Core - Documents

Event	Description
`core.document.uploaded`	A new document was uploaded to Core
`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 Core

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

Clickwraps

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

The event registry also declares vault.document.* and vault.folder.* names. Those are reserved for future use and are not emitted today - subscribing to them delivers nothing.

Overview

API Key Access

OAuth App Access

Webhooks

How Webhooks Work

Registering a Webhook

Authentication & Verification

Retry Policy

Common Payload Fields

Available Events

Core - Documents

Flows - Workflows

Flows - Tasks

Clickwraps

​How Webhooks Work

​Registering a Webhook

​Authentication & Verification

​Retry Policy

​Common Payload Fields

​Available Events

​Core - Documents

​Flows - Workflows

​Flows - Tasks

​Clickwraps

How Webhooks Work

Registering a Webhook

Authentication & Verification

Retry Policy

Common Payload Fields

Available Events

Core - Documents

Flows - Workflows

Flows - Tasks

Clickwraps