Webhooks

import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';

Twenty 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

Twenty sends webhooks for these event types:

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": "[email protected]",
    "createdAt": "2025-02-10T15:30:45Z",
    "createdBy": "user_123"
  },
  "timestamp": "2025-02-10T15:30:50Z"
}

Webhook Validation

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

Headers

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

For receiving external data, see Set Up a Webhook Trigger.