mirror of
https://github.com/twentyhq/twenty
synced 2026-04-21 13:37:22 +00:00
5d438bb70c
## Summary - **New Getting Started section** with quickstart guide and restructured navigation - **Halftone-style illustrations** for User Guide and Developer introduction cards using a Canvas 2D filter script - **Removed hero images** (`image:` frontmatter + `<Frame><img>` blocks) from all user-guide article pages - **Cleaned up translations** (13 languages): removed hero images and updated introduction cards to use halftone style - **Cleaned up twenty-ui pages**: removed outdated hero images from component docs - **Deleted orphaned images**: `table.png`, `kanban.png` - **Developer page**: fixed duplicate icon, switched to 3-column layout ## Test plan - [ ] Verify docs site builds without errors - [ ] Check User Guide introduction page renders halftone card images in both light and dark mode - [ ] Check Developer introduction page renders 3-column layout with distinct icons - [ ] Confirm article pages no longer show hero images at the top - [ ] Spot-check a few translated pages to ensure hero images are removed 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: github-actions <github-actions@twenty.com>
117 lines
3.4 KiB
Text
117 lines
3.4 KiB
Text
---
|
|
title: Webhooks
|
|
icon: "satellite-dish"
|
|
description: Get notified when records change — HTTP POST to your endpoint on every create, update, or delete.
|
|
---
|
|
|
|
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.
|
|
|
|
<VimeoEmbed videoId="928786708" title="Creating a webhook" />
|
|
|
|
### Manage Webhooks
|
|
|
|
**Edit**: Click the webhook → Update URL → **Save**
|
|
|
|
**Delete**: Click the webhook → **Delete** → Confirm
|
|
|
|
## Events
|
|
|
|
Twenty sends webhooks for these event types:
|
|
|
|
| Event | Example |
|
|
|-------|---------|
|
|
| **Record Created** | `person.created`, `company.created`, `note.created` |
|
|
| **Record Updated** | `person.updated`, `company.updated`, `opportunity.updated` |
|
|
| **Record Deleted** | `person.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:
|
|
|
|
```json
|
|
{
|
|
"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"
|
|
}
|
|
```
|
|
|
|
| Field | Description |
|
|
|-------|-------------|
|
|
| `event` | What happened (e.g., `person.created`) |
|
|
| `data` | The full record that was created/updated/deleted |
|
|
| `timestamp` | When the event occurred (UTC) |
|
|
|
|
<Note>
|
|
Respond with a **2xx HTTP status** (200-299) to acknowledge receipt. Non-2xx responses are logged as delivery failures.
|
|
</Note>
|
|
|
|
## Webhook Validation
|
|
|
|
Twenty signs each webhook request for security. Validate signatures to ensure requests are authentic.
|
|
|
|
### Headers
|
|
|
|
| Header | Description |
|
|
|--------|-------------|
|
|
| `X-Twenty-Webhook-Signature` | HMAC SHA256 signature |
|
|
| `X-Twenty-Webhook-Timestamp` | Request 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)
|
|
|
|
```javascript
|
|
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
|
|
|
|
| Method | Direction | Use Case |
|
|
|--------|-----------|----------|
|
|
| **Webhooks** | OUT | Automatically notify external systems of any record change |
|
|
| **Workflow + HTTP Request** | OUT | Send data out with custom logic (filters, transformations) |
|
|
| **Workflow Webhook Trigger** | IN | Receive data into Twenty from external systems |
|
|
|
|
For receiving external data, see [Set Up a Webhook Trigger](/user-guide/workflows/how-tos/connect-to-other-tools/set-up-a-webhook-trigger).
|