snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/developers/extend/capabilities/apis.mdx

@@ -0,0 +1,141 @@
+---
+title: APIs
+description: Query and modify your CRM data programmatically using REST or GraphQL.
+---
+
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+Twenty was built to be developer-friendly, offering powerful APIs that adapt to your custom data model. We provide four distinct API types to meet different integration needs.
+
+## Developer-First Approach
+
+Twenty generates APIs specifically for your data model:
+- **No long IDs required**: Use your object and field names directly in endpoints
+- **Standard and custom objects treated equally**: Your custom objects get the same API treatment as built-in ones
+- **Dedicated endpoints**: Each object and field gets its own API endpoint
+- **Custom documentation**: Generated specifically for your workspace's data model
+
+<Note>
+Your personalized API documentation is available under **Settings → API & Webhooks** after creating an API key. Since Twenty generates APIs that match your custom data model, the documentation is unique to your workspace.
+</Note>
+
+## The Two API Types
+
+### Core API
+Accessed on `/rest/` or `/graphql/`
+
+Work with your actual **records** (the data):
+- Create, read, update, delete People, Companies, Opportunities, etc.
+- Query and filter data
+- Manage record relationships
+
+### Metadata API
+Accessed on `/rest/metadata/` or `/metadata/`
+
+Manage your **workspace and data model**:
+- Create, modify, or delete objects and fields
+- Configure workspace settings
+- Define relationships between objects
+
+## REST vs GraphQL
+
+Both Core and Metadata APIs are available in REST and GraphQL formats:
+
+| Format | Available Operations |
+|--------|---------------------|
+| **REST** | CRUD, batch operations, upserts |
+| **GraphQL** | Same + **batch upserts**, relationship queries in one call |
+
+Choose based on your needs — both formats access the same data.
+
+## API Endpoints
+
+| Environment | Base URL |
+|-------------|----------|
+| **Cloud** | `https://api.twenty.com/` |
+| **Self-Hosted** | `https://{your-domain}/` |
+
+## Authentication
+
+Every API request requires an API key in the header:
+
+```
+Authorization: Bearer YOUR_API_KEY
+```
+
+### Create an API Key
+
+1. Go to **Settings → APIs & Webhooks**
+2. Click **+ Create key**
+3. Configure:
+   - **Name**: Descriptive name for the key
+   - **Expiration Date**: When the key expires
+4. Click **Save**
+5. **Copy immediately** — the key is only shown once
+
+<VimeoEmbed videoId="928786722" title="Creating API key" />
+
+<Warning>
+Your API key grants access to sensitive data. Don't share it with untrusted services. If compromised, disable it immediately and generate a new one.
+</Warning>
+
+### Assign a Role to an API Key
+
+For better security, assign a specific role to limit access:
+
+1. Go to **Settings → Members → Roles**
+2. Click on the role to assign
+3. Open the **Assignment** tab
+4. Under **API Keys**, click **+ Assign to API key**
+5. Select the API key
+
+The key will inherit that role's permissions. See [Permissions](/user-guide/permissions-access/capabilities/permissions) for details.
+
+### Manage API Keys
+
+**Regenerate**: Settings → APIs & Webhooks → Click key → **Regenerate**
+
+**Delete**: Settings → APIs & Webhooks → Click key → **Delete**
+
+## API Playground
+
+Test your APIs directly in the browser with our built-in playground — available for both **REST** and **GraphQL**.
+
+### Access the Playground
+
+1. Go to **Settings → APIs & Webhooks**
+2. Create an API key (required)
+3. Click on **REST API** or **GraphQL API** to open the playground
+
+### What You Get
+
+- **Interactive documentation**: Generated for your specific data model
+- **Live testing**: Execute real API calls against your workspace
+- **Schema explorer**: Browse available objects, fields, and relationships
+- **Request builder**: Construct queries with autocomplete
+
+The playground reflects your custom objects and fields, so documentation is always accurate for your workspace.
+
+## Batch Operations
+
+Both REST and GraphQL support batch operations:
+- **Batch size**: Up to 60 records per request
+- **Operations**: Create, update, delete multiple records
+
+**GraphQL-only features:**
+- **Batch Upsert**: Create or update in one call
+- Use plural object names (e.g., `CreateCompanies` instead of `CreateCompany`)
+
+## Rate Limits
+
+API requests are throttled to ensure platform stability:
+
+| Limit | Value |
+|-------|-------|
+| **Requests** | 100 calls per minute |
+| **Batch size** | 60 records per call |
+
+<Tip>
+Use batch operations to maximize throughput — process up to 60 records in a single API call instead of making individual requests.
+</Tip>
+

packages/twenty-docs/developers/extend/capabilities/webhooks.mdx

@@ -0,0 +1,113 @@
+---
+title: Webhooks
+description: Receive real-time notifications when events occur in your CRM.
+---
+
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+
+Webhooks push data to your systems in real-time when events occur in Twenty — no polling required. Use them to keep external systems in sync, trigger automations, or send alerts.
+
+## 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 isValid = expectedSignature === req.headers["x-twenty-webhook-signature"];
+```
+
+## 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).