Skip to main content
Clara sends an HTTP POST to your URL whenever a record is created, updated, or deleted. All object types are covered, including custom objects.

​
Create a Webhook

  1. Go to Settings → APIs & Webhooks → Webhooks
  2. Click + Create webhook
  3. Enter your webhook URL (must be publicly accessible)
  4. Click Save
The webhook activates immediately and starts sending notifications.

​
Manage Webhooks

Edit: Click the webhook → Update URL → Save Delete: Click the webhook → Delete → Confirm

​
Events

Clara sends webhooks for these event types:
EventExample
Record Createdperson.created, company.created, note.created
Record Updatedperson.updated, company.updated, opportunity.updated
Record Deletedperson.deleted, company.deleted
All event types are sent to your webhook URL. Event filtering may be added in future releases.

​
Payload Format

Each webhook sends an HTTP POST with a JSON body: 
{
  "event": "person.created",
  "data": {
    "id": "abc12345",
    "firstName": "Alice",
    "lastName": "Doe",
    "email": "alice@example.com",
    "createdAt": "2025-02-10T15:30:45Z",
    "createdBy": "user_123"
  },
  "timestamp": "2025-02-10T15:30:50Z"
}
FieldDescription
eventWhat happened (e.g., person.created)
dataThe full record that was created/updated/deleted
timestampWhen the event occurred (UTC)
Respond with a 2xx HTTP status (200-299) to acknowledge receipt. Non-2xx responses are logged as delivery failures.

​
Webhook Validation

Clara signs each webhook request for security. Validate signatures to ensure requests are authentic.

​
Headers

HeaderDescription
X-Twenty-Webhook-SignatureHMAC SHA256 signature
X-Twenty-Webhook-TimestampRequest timestamp

​
Validation Steps

  1. Get the timestamp from X-Twenty-Webhook-Timestamp
  2. Create the string: {timestamp}:{JSON payload}
  3. Compute HMAC SHA256 using your webhook secret
  4. Compare with X-Twenty-Webhook-Signature

​
Example (Node.js)

const crypto = require("crypto");

const timestamp = req.headers["x-twenty-webhook-timestamp"];
const payload = JSON.stringify(req.body);
const secret = "your-webhook-secret";

const stringToSign = `${timestamp}:${payload}`;
const expectedSignature = crypto
  .createHmac("sha256", secret)
  .update(stringToSign)
  .digest("hex");

const receivedSignature = req.headers["x-twenty-webhook-signature"];
const isValid = crypto.timingSafeEqual(
  Buffer.from(expectedSignature, "hex"),
  Buffer.from(receivedSignature, "hex")
);

​
Webhooks vs Workflows

MethodDirectionUse Case
WebhooksOUTAutomatically notify external systems of any record change
Workflow + HTTP RequestOUTSend data out with custom logic (filters, transformations)
Workflow Webhook TriggerINReceive data into Clara from external systems
For receiving external data, see Set Up a Webhook Trigger.