i18n - docs translations (#17199)
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
This commit is contained in:
github-actions[bot]
committed by
GitHub
GitHub
parent
5bcbe43596
commit
b7fbe1c49e
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: APIs
|
||||
description: Query and modify your CRM data programmatically using REST or GraphQL.
|
||||
description: Abfragen und ändern Sie Ihre CRM-Daten programmatisch mit REST oder GraphQL.
|
||||
---
|
||||
|
||||
import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
|
||||
@@ -9,7 +9,7 @@ Twenty wurde so entwickelt, dass es entwicklerfreundlich ist und leistungsstarke
|
||||
|
||||
## Entwickler-Erst-Ansatz
|
||||
|
||||
Twenty generates APIs specifically for your data model:
|
||||
Twenty generiert APIs speziell für Ihr Datenmodell:
|
||||
|
||||
* **Keine langen IDs erforderlich**: Verwenden Sie Ihre Objekt- und Feldnamen direkt in Endpunkten
|
||||
* **Standard- und benutzerdefinierte Objekte werden gleich behandelt**: Ihre benutzerdefinierten Objekte erhalten dieselbe API-Behandlung wie integrierte
|
||||
@@ -17,131 +17,131 @@ Twenty generates APIs specifically for your data model:
|
||||
* **Benutzerdefinierte Dokumentation**: Speziell für das Datenmodell Ihres Arbeitsplatzes generiert
|
||||
|
||||
<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.
|
||||
Ihre personalisierte API-Dokumentation ist nach dem Erstellen eines API-Schlüssels unter **Einstellungen → API & Webhooks** verfügbar. Da Twenty APIs erzeugt, die Ihrem benutzerdefinierten Datenmodell entsprechen, ist die Dokumentation für Ihren Arbeitsbereich einzigartig.
|
||||
</Note>
|
||||
|
||||
## The Two API Types
|
||||
## Die beiden API-Typen
|
||||
|
||||
### Core API
|
||||
|
||||
Zugriff auf `/rest/` oder `/graphql/`
|
||||
|
||||
Work with your actual **records** (the data):
|
||||
Arbeiten Sie mit Ihren tatsächlichen **Datensätzen** (den Daten):
|
||||
|
||||
* Create, read, update, delete People, Companies, Opportunities, etc.
|
||||
* Query and filter data
|
||||
* Personen, Unternehmen, Opportunities usw. erstellen, lesen, aktualisieren und löschen
|
||||
* Daten abfragen und filtern
|
||||
* Verwalten von Datensatzbeziehungen
|
||||
|
||||
### Metadata API
|
||||
|
||||
Zugriff auf `/rest/metadata/` oder `/metadata/`
|
||||
|
||||
Manage your **workspace and data model**:
|
||||
Verwalten Sie Ihren **Arbeitsbereich und Ihr Datenmodell**:
|
||||
|
||||
* Create, modify, or delete objects and fields
|
||||
* Objekte und Felder erstellen, ändern oder löschen
|
||||
* Konfigurieren der Arbeitsbereichseinstellungen
|
||||
* Define relationships between objects
|
||||
* Beziehungen zwischen Objekten definieren
|
||||
|
||||
## REST vs GraphQL
|
||||
|
||||
Both Core and Metadata APIs are available in REST and GraphQL formats:
|
||||
Sowohl Core- als auch Metadata-APIs sind in REST- und GraphQL-Formaten verfügbar:
|
||||
|
||||
| Format | Available Operations |
|
||||
| ----------- | ---------------------------------------------------------- |
|
||||
| **REST** | CRUD, batch operations, upserts |
|
||||
| **GraphQL** | Same + **batch upserts**, relationship queries in one call |
|
||||
| Format | Verfügbare Vorgänge |
|
||||
| ----------- | ------------------------------------------------------------------- |
|
||||
| **REST** | CRUD, Batch-Vorgänge, Upserts |
|
||||
| **GraphQL** | Dasselbe plus **Batch-Upserts**, Beziehungsabfragen in einem Aufruf |
|
||||
|
||||
Choose based on your needs — both formats access the same data.
|
||||
Wählen Sie je nach Bedarf — beide Formate greifen auf dieselben Daten zu.
|
||||
|
||||
## API-Endpunkte
|
||||
|
||||
| Environment | Base URL |
|
||||
| --------------- | ------------------------- |
|
||||
| **Cloud** | `https://api.twenty.com/` |
|
||||
| **Self-Hosted** | `https://{your-domain}/` |
|
||||
| Umgebung | Basis-URL |
|
||||
| ----------------- | ------------------------- |
|
||||
| **Cloud** | `https://api.twenty.com/` |
|
||||
| **Selbsthosting** | `https://{your-domain}/` |
|
||||
|
||||
## Authentifizierung
|
||||
|
||||
Every API request requires an API key in the header:
|
||||
Jede API-Anfrage erfordert einen API-Schlüssel im Header:
|
||||
|
||||
```
|
||||
Authorization: Bearer YOUR_API_KEY
|
||||
```
|
||||
|
||||
### Create an API Key
|
||||
### API-Schlüssel erstellen
|
||||
|
||||
1. Gehen Sie zu **Einstellungen → APIs & Webhooks**
|
||||
2. Click **+ Create key**
|
||||
2. Klicken Sie auf **+ Schlüssel erstellen**
|
||||
3. Konfigurieren:
|
||||
* **Name**: Descriptive name for the key
|
||||
* **Expiration Date**: When the key expires
|
||||
* **Name**: Beschreibender Name für den Schlüssel
|
||||
* **Ablaufdatum**: Wann der Schlüssel abläuft
|
||||
4. Klicken Sie auf **Speichern**
|
||||
5. **Copy immediately** — the key is only shown once
|
||||
5. **Sofort kopieren** — der Schlüssel wird nur einmal angezeigt
|
||||
|
||||
<VimeoEmbed videoId="928786722" title="Creating API key" />
|
||||
<VimeoEmbed videoId="928786722" title="API-Schlüssel erstellen" />
|
||||
|
||||
<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.
|
||||
Ihr API-Schlüssel gewährt Zugriff auf sensible Daten. Teilen Sie ihn nicht mit nicht vertrauenswürdigen Diensten. Wenn er kompromittiert wurde, deaktivieren Sie ihn umgehend und erstellen Sie einen neuen.
|
||||
</Warning>
|
||||
|
||||
### Assign a Role to an API Key
|
||||
### Einem API-Schlüssel eine Rolle zuweisen
|
||||
|
||||
For better security, assign a specific role to limit access:
|
||||
Für mehr Sicherheit weisen Sie eine spezifische Rolle zu, um den Zugriff zu beschränken:
|
||||
|
||||
1. Gehen Sie zu **Einstellungen → Rollen**
|
||||
2. Click on the role to assign
|
||||
2. Klicken Sie auf die Rolle, die Sie zuweisen möchten
|
||||
3. Öffnen Sie den Tab **Zuweisungen**
|
||||
4. Under **API Keys**, click **+ Assign to API key**
|
||||
5. Select the API key
|
||||
4. Unter **API-Schlüssel** auf **+ API-Schlüssel zuweisen** klicken
|
||||
5. Wählen Sie den API-Schlüssel aus
|
||||
|
||||
The key will inherit that role's permissions. See [Permissions](/l/de/user-guide/permissions-access/capabilities/permissions) for details.
|
||||
Der Schlüssel übernimmt die Berechtigungen dieser Rolle. Siehe [Berechtigungen](/l/de/user-guide/permissions-access/capabilities/permissions) für Details.
|
||||
|
||||
### API-Schlüssel verwalten
|
||||
|
||||
**Regenerate**: Settings → APIs & Webhooks → Click key → **Regenerate**
|
||||
**Neu generieren**: Einstellungen → APIs & Webhooks → Schlüssel anklicken → **Neu generieren**
|
||||
|
||||
**Delete**: Settings → APIs & Webhooks → Click key → **Delete**
|
||||
**Löschen**: Einstellungen → APIs & Webhooks → Schlüssel anklicken → **Löschen**
|
||||
|
||||
## API Playground
|
||||
## API-Playground
|
||||
|
||||
Test your APIs directly in the browser with our built-in playground — available for both **REST** and **GraphQL**.
|
||||
Testen Sie Ihre APIs direkt im Browser mit unserem integrierten Playground — verfügbar für **REST** und **GraphQL**.
|
||||
|
||||
### Access the Playground
|
||||
### Auf den Playground zugreifen
|
||||
|
||||
1. Gehen Sie zu **Einstellungen → APIs & Webhooks**
|
||||
2. Create an API key (required)
|
||||
3. Click on **REST API** or **GraphQL API** to open the playground
|
||||
2. API-Schlüssel erstellen (erforderlich)
|
||||
3. Klicken Sie auf **REST API** oder **GraphQL API**, um den Playground zu öffnen
|
||||
|
||||
### What You Get
|
||||
### Was Sie erhalten
|
||||
|
||||
* **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
|
||||
* **Interaktive Dokumentation**: Für Ihr spezifisches Datenmodell generiert
|
||||
* **Live-Tests**: Führen Sie echte API-Aufrufe gegen Ihren Arbeitsbereich aus
|
||||
* **Schema-Explorer**: Verfügbare Objekte, Felder und Beziehungen durchsuchen
|
||||
* **Request-Builder**: Abfragen mit Autovervollständigung erstellen
|
||||
|
||||
The playground reflects your custom objects and fields, so documentation is always accurate for your workspace.
|
||||
Der Playground spiegelt Ihre benutzerdefinierten Objekte und Felder wider, sodass die Dokumentation für Ihren Arbeitsbereich stets korrekt ist.
|
||||
|
||||
## Batch-Vorgänge
|
||||
|
||||
Both REST and GraphQL support batch operations:
|
||||
Sowohl REST als auch GraphQL unterstützen Batch-Vorgänge:
|
||||
|
||||
* **Batch-Größe**: Bis zu 60 Datensätze pro Anfrage
|
||||
* **Operations**: Create, update, delete multiple records
|
||||
* **Vorgänge**: Mehrere Datensätze erstellen, aktualisieren, löschen
|
||||
|
||||
**GraphQL-only features:**
|
||||
**GraphQL-Exklusivfunktionen:**
|
||||
|
||||
* **Batch Upsert**: Create or update in one call
|
||||
* Use plural object names (e.g., `CreateCompanies` instead of `CreateCompany`)
|
||||
* **Batch-Upsert**: Erstellen oder Aktualisieren in einem Aufruf
|
||||
* Verwenden Sie Pluralobjektnamen (z. B. `CreateCompanies` statt `CreateCompany`)
|
||||
|
||||
## Rate Limits
|
||||
|
||||
API requests are throttled to ensure platform stability:
|
||||
API-Anfragen werden gedrosselt, um die Stabilität der Plattform zu gewährleisten:
|
||||
|
||||
| Limit | Wert |
|
||||
| -------------- | -------------------- |
|
||||
| **Requests** | 100 calls per minute |
|
||||
| **Batch size** | 60 records per call |
|
||||
| Limit | Wert |
|
||||
| --------------- | ------------------------ |
|
||||
| **Anfragen** | 100 Aufrufe pro Minute |
|
||||
| **Batch-Größe** | 60 Datensätze pro Aufruf |
|
||||
|
||||
<Tip>
|
||||
Use batch operations to maximize throughput — process up to 60 records in a single API call instead of making individual requests.
|
||||
Verwenden Sie Batch-Vorgänge, um den Durchsatz zu maximieren — verarbeiten Sie bis zu 60 Datensätze in einem einzelnen API-Aufruf, statt einzelne Anfragen zu senden.
|
||||
</Tip>
|
||||
|
||||
@@ -1,34 +1,34 @@
|
||||
---
|
||||
title: Twenty Apps
|
||||
description: Build and manage Twenty customizations as code.
|
||||
title: Twenty-Apps
|
||||
description: Twenty-Anpassungen als Code erstellen und verwalten.
|
||||
---
|
||||
|
||||
<Warning>
|
||||
Apps are currently in alpha testing. The feature is functional but still evolving.
|
||||
Apps befinden sich derzeit in der Alpha-Testphase. Die Funktion ist funktionsfähig, entwickelt sich jedoch noch weiter.
|
||||
</Warning>
|
||||
|
||||
## What Are Apps?
|
||||
## Was sind Apps?
|
||||
|
||||
Apps let you build and manage Twenty customizations **as code**. Instead of configuring everything through the UI, you define your data model and serverless functions in code — making it faster to build, maintain, and roll out to multiple workspaces.
|
||||
Mit Apps können Sie Twenty-Anpassungen **als Code** erstellen und verwalten. Anstatt alles über die UI zu konfigurieren, definieren Sie Ihr Datenmodell und serverlose Funktionen im Code — das beschleunigt Entwicklung, Wartung und Rollout auf mehrere Workspaces.
|
||||
|
||||
**What you can do today:**
|
||||
**Was Sie heute tun können:**
|
||||
|
||||
* Define custom objects and fields as code (managed data model)
|
||||
* Build serverless functions with custom triggers
|
||||
* Deploy the same app across multiple workspaces
|
||||
* Benutzerdefinierte Objekte und Felder als Code definieren (verwaltetes Datenmodell)
|
||||
* Serverlose Funktionen mit benutzerdefinierten Triggern erstellen
|
||||
* Dieselbe App in mehreren Workspaces bereitstellen
|
||||
|
||||
**Coming soon:**
|
||||
**Bald verfügbar:**
|
||||
|
||||
* Custom UI layouts and components
|
||||
* Benutzerdefinierte UI-Layouts und Komponenten
|
||||
|
||||
## Voraussetzungen
|
||||
|
||||
* Node.js 24+ and Yarn 4
|
||||
* A Twenty workspace and an API key (create one at https://app.twenty.com/settings/api-webhooks)
|
||||
* Node.js 24+ und Yarn 4
|
||||
* Ein Twenty-Workspace und ein API-Schlüssel (unter https://app.twenty.com/settings/api-webhooks erstellen)
|
||||
|
||||
## Erste Schritte
|
||||
|
||||
Create a new app using the official scaffolder, then authenticate and start developing:
|
||||
Erstellen Sie mit dem offiziellen Scaffolder eine neue App, authentifizieren Sie sich und beginnen Sie mit der Entwicklung:
|
||||
|
||||
```bash filename="Terminal"
|
||||
# Scaffold a new app
|
||||
@@ -64,18 +64,18 @@ yarn uninstall
|
||||
yarn help
|
||||
```
|
||||
|
||||
See also: the CLI reference pages for [create-twenty-app](https://www.npmjs.com/package/create-twenty-app) and [twenty-sdk CLI](https://www.npmjs.com/package/twenty-sdk).
|
||||
Siehe auch: die CLI-Referenzseiten für [create-twenty-app](https://www.npmjs.com/package/create-twenty-app) und [twenty-sdk CLI](https://www.npmjs.com/package/twenty-sdk).
|
||||
|
||||
## Project structure (scaffolded)
|
||||
## Projektstruktur (vom Scaffolder erzeugt)
|
||||
|
||||
When you run `npx create-twenty-app@latest my-twenty-app`, the scaffolder:
|
||||
Wenn Sie `npx create-twenty-app@latest my-twenty-app` ausführen, erledigt der Scaffolder Folgendes:
|
||||
|
||||
* Copies a minimal base application into `my-twenty-app/`
|
||||
* Adds a local `twenty-sdk` dependency and Yarn 4 configuration
|
||||
* Creates config files and scripts wired to the `twenty` CLI
|
||||
* Generates a default application config and a default function role
|
||||
* Kopiert eine minimale Basisanwendung nach `my-twenty-app/`
|
||||
* Fügt eine lokale `twenty-sdk`-Abhängigkeit und die Yarn-4-Konfiguration hinzu
|
||||
* Erstellt Konfigurationsdateien und Skripte, die an die `twenty`-CLI angebunden sind
|
||||
* Generiert eine Standard-Anwendungskonfiguration und eine Standard-Funktionsrolle
|
||||
|
||||
A freshly scaffolded app looks like this:
|
||||
Eine frisch erzeugte App sieht so aus:
|
||||
|
||||
```text filename="my-twenty-app/"
|
||||
my-twenty-app/
|
||||
@@ -99,21 +99,21 @@ my-twenty-app/
|
||||
utils/ # Optional - handler implementations & utilities
|
||||
```
|
||||
|
||||
### Convention-over-configuration
|
||||
### Konvention vor Konfiguration
|
||||
|
||||
Applications use a **convention-over-configuration** approach where entities are detected by their file suffix. This allows flexible organization within the `src/app/` folder:
|
||||
Anwendungen verwenden einen Ansatz **Konvention vor Konfiguration**, bei dem Entitäten anhand ihrer Dateiendung erkannt werden. Dies ermöglicht eine flexible Organisation im Ordner `src/app/`:
|
||||
|
||||
| File suffix | Entity type |
|
||||
| --------------- | ------------------------------- |
|
||||
| `*.object.ts` | Custom object definitions |
|
||||
| `*.function.ts` | Serverless function definitions |
|
||||
| `*.role.ts` | Role definitions |
|
||||
| Dateiendung | Entitätstyp |
|
||||
| --------------- | ------------------------------------- |
|
||||
| `*.object.ts` | Benutzerdefinierte Objektdefinitionen |
|
||||
| `*.function.ts` | Definitionen serverloser Funktionen |
|
||||
| `*.role.ts` | Rollendefinitionen |
|
||||
|
||||
### Supported folder organizations
|
||||
### Unterstützte Ordnerorganisationen
|
||||
|
||||
You can organize your entities in any of these patterns:
|
||||
Sie können Ihre Entitäten nach einem der folgenden Muster organisieren:
|
||||
|
||||
**Traditional (by type):**
|
||||
**Traditionell (nach Typ):**
|
||||
|
||||
```text
|
||||
src/app/
|
||||
@@ -126,7 +126,7 @@ src/app/
|
||||
└── admin.role.ts
|
||||
```
|
||||
|
||||
**Feature-based:**
|
||||
**Feature-basiert:**
|
||||
|
||||
```text
|
||||
src/app/
|
||||
@@ -137,7 +137,7 @@ src/app/
|
||||
└── postCardAdmin.role.ts
|
||||
```
|
||||
|
||||
**Flat:**
|
||||
**Flach:**
|
||||
|
||||
```text
|
||||
src/app/
|
||||
@@ -147,34 +147,34 @@ src/app/
|
||||
└── admin.role.ts
|
||||
```
|
||||
|
||||
At a high level:
|
||||
Auf hoher Ebene:
|
||||
|
||||
* **package.json**: Declares the app name, version, engines (Node 24+, Yarn 4), and adds `twenty-sdk` plus scripts like `dev`, `sync`, `generate`, `create-entity`, `logs`, `uninstall`, and `auth` that delegate to the local `twenty` CLI.
|
||||
* **.gitignore**: Ignores common artifacts such as `node_modules`, `.yarn`, `generated/` (typed client), `dist/`, `build/`, coverage folders, log files, and `.env*` files.
|
||||
* **yarn.lock**, **.yarnrc.yml**, **.yarn/**: Lock and configure the Yarn 4 toolchain used by the project.
|
||||
* **.nvmrc**: Pins the Node.js version expected by the project.
|
||||
* **eslint.config.mjs** and **tsconfig.json**: Provide linting and TypeScript configuration for your app's TypeScript sources.
|
||||
* **README.md**: A short README in the app root with basic instructions.
|
||||
* **src/app/**: The main place where you define your application-as-code:
|
||||
* `application.config.ts`: Global configuration for your app (metadata and runtime wiring). See "Application config" below.
|
||||
* `*.role.ts`: Role definitions used by your serverless functions. See "Default function role" below.
|
||||
* `*.object.ts`: Custom object definitions.
|
||||
* `*.function.ts`: Serverless function definitions.
|
||||
* **src/utils/**: Optional folder for handler implementations and utilities.
|
||||
* **package.json**: Deklariert App-Name, Version, Engines (Node 24+, Yarn 4) und fügt `twenty-sdk` sowie Skripte wie `dev`, `sync`, `generate`, `create-entity`, `logs`, `uninstall` und `auth` hinzu, die an die lokale `twenty`-CLI delegieren.
|
||||
* **.gitignore**: Ignoriert übliche Artefakte wie `node_modules`, `.yarn`, `generated/` (typisierter Client), `dist/`, `build/`, Coverage-Ordner, Logdateien und `.env*`-Dateien.
|
||||
* **yarn.lock**, **.yarnrc.yml**, **.yarn/**: Fixieren und konfigurieren die vom Projekt verwendete Yarn-4-Toolchain.
|
||||
* **.nvmrc**: Legt die vom Projekt erwartete Node.js-Version fest.
|
||||
* **eslint.config.mjs** und **tsconfig.json**: Stellen Linting und TypeScript-Konfiguration für die TypeScript-Quellen Ihrer App bereit.
|
||||
* **README.md**: Ein kurzes README im App-Root mit grundlegenden Anweisungen.
|
||||
* **src/app/**: Der Hauptort, an dem Sie Ihre Anwendung als Code definieren:
|
||||
* `application.config.ts`: Globale Konfiguration für Ihre App (Metadaten und Laufzeit-Anbindung). Siehe unten „Anwendungskonfiguration“.
|
||||
* `*.role.ts`: Rollendefinitionen, die von Ihren serverlosen Funktionen verwendet werden. Siehe unten „Standard-Funktionsrolle“.
|
||||
* `*.object.ts`: Benutzerdefinierte Objektdefinitionen.
|
||||
* `*.function.ts`: Definitionen serverloser Funktionen.
|
||||
* **src/utils/**: Optionaler Ordner für Handler-Implementierungen und Utilities.
|
||||
|
||||
Later commands will add more files and folders:
|
||||
Spätere Befehle fügen weitere Dateien und Ordner hinzu:
|
||||
|
||||
* `yarn generate` will create a `generated/` folder (typed Twenty client + workspace types).
|
||||
* `yarn create-entity` will add entity definition files under `src/app/` for your custom objects, functions, or roles.
|
||||
* `yarn generate` erstellt einen `generated/`-Ordner (typisierter Twenty-Client + Workspace-Typen).
|
||||
* `yarn create-entity` fügt unter `src/app/` Entitätsdefinitionsdateien für Ihre benutzerdefinierten Objekte, Funktionen oder Rollen hinzu.
|
||||
|
||||
## Authentifizierung
|
||||
|
||||
The first time you run `yarn auth`, you'll be prompted for:
|
||||
Wenn Sie `yarn auth` zum ersten Mal ausführen, werden Sie nach Folgendem gefragt:
|
||||
|
||||
* API URL (defaults to http://localhost:3000 or your current workspace profile)
|
||||
* API key
|
||||
* API-URL (standardmäßig http://localhost:3000 oder Ihr aktuelles Workspace-Profil)
|
||||
* API-Schlüssel
|
||||
|
||||
Your credentials are stored per-user in `~/.twenty/config.json`. You can maintain multiple profiles and switch using `--workspace <name>`.
|
||||
Ihre Anmeldedaten werden pro Benutzer in `~/.twenty/config.json` gespeichert. Sie können mehrere Profile verwalten und mit `--workspace <name>` wechseln.
|
||||
|
||||
Beispiele:
|
||||
|
||||
@@ -186,26 +186,26 @@ yarn auth
|
||||
yarn auth --workspace my-custom-workspace
|
||||
```
|
||||
|
||||
## Use the SDK resources (types & config)
|
||||
## SDK-Ressourcen verwenden (Typen & Konfiguration)
|
||||
|
||||
The twenty-sdk provides typed building blocks and helper functions you use inside your app. Below are the key pieces you'll touch most often.
|
||||
Das twenty-sdk stellt typisierte Bausteine und Hilfsfunktionen bereit, die Sie in Ihrer App verwenden. Im Folgenden finden Sie die wichtigsten Bausteine, mit denen Sie am häufigsten arbeiten.
|
||||
|
||||
### Helper functions
|
||||
### Hilfsfunktionen
|
||||
|
||||
The SDK provides four helper functions with built-in validation for defining your app entities:
|
||||
Das SDK stellt vier Hilfsfunktionen mit eingebauter Validierung bereit, um Ihre App-Entitäten zu definieren:
|
||||
|
||||
| Function | Zweck |
|
||||
| ------------------ | -------------------------------------------- |
|
||||
| `defineApp()` | Configure application metadata |
|
||||
| `defineObject()` | Define custom objects with fields |
|
||||
| `defineFunction()` | Define serverless functions with handlers |
|
||||
| `defineRole()` | Configure role permissions and object access |
|
||||
| Funktion | Zweck |
|
||||
| ------------------ | ---------------------------------------------------- |
|
||||
| `defineApp()` | Anwendungsmetadaten konfigurieren |
|
||||
| `defineObject()` | Benutzerdefinierte Objekte mit Feldern definieren |
|
||||
| `defineFunction()` | Serverlose Funktionen mit Handlern definieren |
|
||||
| `defineRole()` | Rollenberechtigungen und Objektzugriff konfigurieren |
|
||||
|
||||
These functions validate your configuration at runtime and provide better IDE autocompletion and type safety.
|
||||
Diese Funktionen validieren Ihre Konfiguration zur Laufzeit und bieten bessere IDE-Autovervollständigung sowie Typsicherheit.
|
||||
|
||||
### Defining objects
|
||||
### Objekte definieren
|
||||
|
||||
Custom objects describe both schema and behavior for records in your workspace. Use `defineObject()` to define objects with built-in validation:
|
||||
Benutzerdefinierte Objekte beschreiben sowohl Schema als auch Verhalten für Datensätze in Ihrem Workspace. Verwenden Sie `defineObject()`, um Objekte mit eingebauter Validierung zu definieren:
|
||||
|
||||
```typescript
|
||||
// src/app/postCard.object.ts
|
||||
@@ -276,20 +276,20 @@ export default defineObject({
|
||||
});
|
||||
```
|
||||
|
||||
Key points:
|
||||
Hauptpunkte:
|
||||
|
||||
* Use `defineObject()` for built-in validation and better IDE support.
|
||||
* The `universalIdentifier` must be unique and stable across deployments.
|
||||
* Each field requires a `name`, `type`, `label`, and its own stable `universalIdentifier`.
|
||||
* The `fields` array is optional — you can define objects without custom fields.
|
||||
* You can scaffold new objects using `yarn create-entity`, which guides you through naming, fields, and relationships.
|
||||
* Verwenden Sie `defineObject()` für eingebaute Validierung und bessere IDE-Unterstützung.
|
||||
* Der `universalIdentifier` muss eindeutig und über Deployments hinweg stabil sein.
|
||||
* Jedes Feld benötigt `name`, `type`, `label` und einen eigenen stabilen `universalIdentifier`.
|
||||
* Das Array `fields` ist optional — Sie können Objekte ohne benutzerdefinierte Felder definieren.
|
||||
* Sie können mit `yarn create-entity` neue Objekte erzeugen; der Assistent führt Sie durch Benennung, Felder und Beziehungen.
|
||||
|
||||
<Note>
|
||||
**Base fields are created automatically.** When you define a custom object, Twenty automatically adds standard fields such as `name`, `createdAt`, `updatedAt`, `createdBy`, `position`, and `deletedAt`. You don't need to define these in your `fields` array — only add your custom fields.
|
||||
**Basisfelder werden automatisch erstellt.** Wenn Sie ein benutzerdefiniertes Objekt definieren, fügt Twenty automatisch Standardfelder wie `name`, `createdAt`, `updatedAt`, `createdBy`, `position` und `deletedAt` hinzu. Sie müssen diese nicht in Ihrem `fields`-Array definieren — fügen Sie nur Ihre benutzerdefinierten Felder hinzu.
|
||||
</Note>
|
||||
|
||||
<Accordion title="Alternative: Decorator-based syntax">
|
||||
You can also define objects using TypeScript decorators. This approach uses class-based syntax with `@Object`, `@Field`, and `@Relation` decorators:
|
||||
<Accordion title="Alternative: Dekoratorbasierte Syntax">
|
||||
Sie können Objekte auch mit TypeScript-Dekoratoren definieren. Dieser Ansatz verwendet klassenbasierte Syntax mit den Dekoratoren `@Object`, `@Field` und `@Relation`:
|
||||
|
||||
```typescript
|
||||
import {
|
||||
@@ -336,18 +336,18 @@ Key points:
|
||||
}
|
||||
```
|
||||
|
||||
Note: The decorator approach requires `experimentalDecorators` in your TypeScript config.
|
||||
Hinweis: Der Dekorator-Ansatz erfordert `experimentalDecorators` in Ihrer TypeScript-Konfiguration.
|
||||
</Accordion>
|
||||
|
||||
### Application config (application.config.ts)
|
||||
### Anwendungskonfiguration (application.config.ts)
|
||||
|
||||
Every app has a single `application.config.ts` file that describes:
|
||||
Jede App hat eine einzelne Datei `application.config.ts`, die Folgendes beschreibt:
|
||||
|
||||
* **Who the app is**: identifiers, display name, and description.
|
||||
* **How its functions run**: which role they use for permissions.
|
||||
* **(Optional) variables**: key–value pairs exposed to your functions as environment variables.
|
||||
* **Was die App ist**: Bezeichner, Anzeigename und Beschreibung.
|
||||
* **Wie ihre Funktionen ausgeführt werden**: welche Rolle sie für Berechtigungen verwenden.
|
||||
* **(Optional) Variablen**: Schlüssel–Wert-Paare, die Ihren Funktionen als Umgebungsvariablen zur Verfügung gestellt werden.
|
||||
|
||||
Use `defineApp()` to define your application configuration:
|
||||
Verwenden Sie `defineApp()`, um Ihre Anwendungskonfiguration zu definieren:
|
||||
|
||||
```typescript
|
||||
// src/app/application.config.ts
|
||||
@@ -371,23 +371,23 @@ export default defineApp({
|
||||
});
|
||||
```
|
||||
|
||||
Notes:
|
||||
Notizen:
|
||||
|
||||
* `universalIdentifier` fields are deterministic IDs you own; generate them once and keep them stable across syncs.
|
||||
* `applicationVariables` become environment variables for your functions (for example, `DEFAULT_RECIPIENT_NAME` is available as `process.env.DEFAULT_RECIPIENT_NAME`).
|
||||
* `functionRoleUniversalIdentifier` must match the role you define in your `*.role.ts` file (see below).
|
||||
* `universalIdentifier`-Felder sind deterministische IDs, die Sie besitzen; generieren Sie sie einmal und halten Sie sie über Synchronisierungen hinweg stabil.
|
||||
* `applicationVariables` werden zu Umgebungsvariablen für Ihre Funktionen (zum Beispiel ist `DEFAULT_RECIPIENT_NAME` als `process.env.DEFAULT_RECIPIENT_NAME` verfügbar).
|
||||
* `functionRoleUniversalIdentifier` muss mit der Rolle übereinstimmen, die Sie in Ihrer `*.role.ts`-Datei definieren (siehe unten).
|
||||
|
||||
#### Roles and permissions
|
||||
#### Rollen und Berechtigungen
|
||||
|
||||
Applications can define roles that encapsulate permissions on your workspace's objects and actions. The field `functionRoleUniversalIdentifier` in `application.config.ts` designates the default role used by your app's serverless functions.
|
||||
Anwendungen können Rollen definieren, die Berechtigungen für die Objekte und Aktionen Ihres Workspaces kapseln. Das Feld `functionRoleUniversalIdentifier` in `application.config.ts` legt die Standardrolle fest, die von den serverlosen Funktionen Ihrer App verwendet wird.
|
||||
|
||||
* The runtime API key injected as `TWENTY_API_KEY` is derived from this default function role.
|
||||
* The typed client will be restricted to the permissions granted to that role.
|
||||
* Follow least‑privilege: create a dedicated role with only the permissions your functions need, then reference its universal identifier.
|
||||
* Der zur Laufzeit als `TWENTY_API_KEY` injizierte API-Schlüssel wird von dieser Standard-Funktionsrolle abgeleitet.
|
||||
* Der typisierte Client ist auf die dieser Rolle gewährten Berechtigungen beschränkt.
|
||||
* Befolgen Sie das Least-Privilege-Prinzip: Erstellen Sie eine dedizierte Rolle nur mit den Berechtigungen, die Ihre Funktionen benötigen, und verweisen Sie dann auf deren universellen Bezeichner.
|
||||
|
||||
##### Default function role (\*.role.ts)
|
||||
##### Standard-Funktionsrolle (\*.role.ts)
|
||||
|
||||
When you scaffold a new app, the CLI also creates a default role file. Use `defineRole()` to define roles with built-in validation:
|
||||
Wenn Sie eine neue App erzeugen, erstellt die CLI auch eine Standard-Rolldatei. Verwenden Sie `defineRole()`, um Rollen mit eingebauter Validierung zu definieren:
|
||||
|
||||
```typescript
|
||||
// src/app/default-function.role.ts
|
||||
@@ -429,37 +429,37 @@ export default defineRole({
|
||||
});
|
||||
```
|
||||
|
||||
The `universalIdentifier` of this role is then referenced in `application.config.ts` as `functionRoleUniversalIdentifier`. In other words:
|
||||
Der `universalIdentifier` dieser Rolle wird anschließend in `application.config.ts` als `functionRoleUniversalIdentifier` referenziert. Anders ausgedrückt:
|
||||
|
||||
* **\*.role.ts** defines what the default function role can do.
|
||||
* **application.config.ts** points to that role so your functions inherit its permissions.
|
||||
* **\*.role.ts** definiert, was die Standard-Funktionsrolle darf.
|
||||
* **application.config.ts** verweist auf diese Rolle, sodass Ihre Funktionen deren Berechtigungen erben.
|
||||
|
||||
Notes:
|
||||
Notizen:
|
||||
|
||||
* Start from the scaffolded role, then progressively restrict it following least‑privilege.
|
||||
* Replace the `objectPermissions` and `fieldPermissions` with the objects/fields your functions need.
|
||||
* `permissionFlags` control access to platform-level capabilities. Keep them minimal; add only what you need.
|
||||
* See a working example in the Hello World app: [`packages/twenty-apps/hello-world/src/roles/function-role.ts`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/hello-world/src/roles/function-role.ts).
|
||||
* Beginnen Sie mit der vorab erstellten Rolle und schränken Sie sie schrittweise gemäß dem Least-Privilege-Prinzip ein.
|
||||
* Ersetzen Sie `objectPermissions` und `fieldPermissions` durch die Objekte/Felder, die Ihre Funktionen benötigen.
|
||||
* `permissionFlags` steuern den Zugriff auf Funktionen auf Plattformebene. Halten Sie sie minimal; fügen Sie nur hinzu, was Sie benötigen.
|
||||
* Ein funktionierendes Beispiel finden Sie in der Hello-World-App: [`packages/twenty-apps/hello-world/src/roles/function-role.ts`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/hello-world/src/roles/function-role.ts).
|
||||
|
||||
### Serverless function config and entrypoint
|
||||
### Konfiguration serverloser Funktionen und Einstiegspunkt
|
||||
|
||||
Each function file uses `defineFunction()` to export a configuration with a handler and optional triggers. Use the `*.function.ts` file suffix for automatic detection.
|
||||
Jede Funktionsdatei verwendet `defineFunction()`, um eine Konfiguration mit einem Handler und optionalen Triggern zu exportieren. Verwenden Sie die Dateiendung `*.function.ts` für die automatische Erkennung.
|
||||
|
||||
```typescript
|
||||
// src/app/createPostCard.function.ts
|
||||
import { defineFunction } from 'twenty-sdk';
|
||||
import type { DatabaseEventPayload, ObjectRecordCreateEvent, CronPayload } from 'twenty-sdk';
|
||||
import type { DatabaseEventPayload, ObjectRecordCreateEvent, CronPayload, RoutePayload } from 'twenty-sdk';
|
||||
import Twenty, { type Person } from '../../generated';
|
||||
|
||||
const handler = async (
|
||||
params:
|
||||
| { name?: string }
|
||||
| RoutePayload
|
||||
| DatabaseEventPayload<ObjectRecordCreateEvent<Person>>
|
||||
| CronPayload,
|
||||
) => {
|
||||
const client = new Twenty(); // generated typed client
|
||||
const name = 'name' in params
|
||||
? params.name ?? process.env.DEFAULT_RECIPIENT_NAME ?? 'Hello world'
|
||||
const name = 'name' in params.queryStringParameters
|
||||
? params.queryStringParameters.name ?? process.env.DEFAULT_RECIPIENT_NAME ?? 'Hello world'
|
||||
: 'Hello world';
|
||||
|
||||
const result = await client.mutation({
|
||||
@@ -502,30 +502,122 @@ export default defineFunction({
|
||||
});
|
||||
```
|
||||
|
||||
Common trigger types:
|
||||
Häufige Trigger-Typen:
|
||||
|
||||
* **route**: Exposes your function on an HTTP path and method **under the `/s/` endpoint**:
|
||||
* **route**: Stellt Ihre Funktion unter einem HTTP-Pfad und einer Methode **unter dem Endpunkt `/s/`** bereit:
|
||||
|
||||
> e.g. `path: '/post-card/create',` -> call on `<APP_URL>/s/post-card/create`
|
||||
> z. B. `path: '/post-card/create',` -> Aufruf unter `<APP_URL>/s/post-card/create`
|
||||
|
||||
* **cron**: Runs your function on a schedule using a CRON expression.
|
||||
* **databaseEvent**: Runs on workspace object lifecycle events
|
||||
* **cron**: Führt Ihre Funktion nach Zeitplan mithilfe eines CRON-Ausdrucks aus.
|
||||
* **databaseEvent**: Wird bei Lebenszyklusereignissen von Workspace-Objekten ausgeführt
|
||||
|
||||
> e.g. `person.created`
|
||||
> z. B. `person.created`
|
||||
|
||||
Notes:
|
||||
Notizen:
|
||||
|
||||
* The `triggers` array is optional. Functions without triggers can be used as utility functions called by other functions.
|
||||
* You can mix multiple trigger types in a single function.
|
||||
* Das Array `triggers` ist optional. Funktionen ohne Trigger können als von anderen Funktionen aufgerufene Utility-Funktionen verwendet werden.
|
||||
* Sie können mehrere Trigger-Typen in einer Funktion kombinieren.
|
||||
|
||||
You can create new functions in two ways:
|
||||
### Route trigger payload
|
||||
|
||||
* **Scaffolded**: Run `yarn create-entity` and choose the option to add a new function. This generates a starter file with a handler and config.
|
||||
* **Manual**: Create a new `*.function.ts` file and use `defineFunction()`, following the same pattern.
|
||||
<Warning>
|
||||
**Breaking change (v1.16, January 2026):** The route trigger payload format has changed. Prior to v1.16, query parameters, path parameters, and body were sent directly as the payload. Starting with v1.16, they are nested inside a structured `RoutePayload` object.
|
||||
|
||||
### Generated typed client
|
||||
**Before v1.16:**
|
||||
|
||||
Run yarn generate to create a local typed client in generated/ based on your workspace schema. Use it in your functions:
|
||||
```typescript
|
||||
const handler = async (params) => {
|
||||
const { param1, param2 } = params; // Direct access
|
||||
};
|
||||
```
|
||||
|
||||
**After v1.16:**
|
||||
|
||||
```typescript
|
||||
const handler = async (event: RoutePayload) => {
|
||||
const { param1, param2 } = event.body; // Access via .body
|
||||
const { queryParam } = event.queryStringParameters;
|
||||
const { id } = event.pathParameters;
|
||||
};
|
||||
```
|
||||
|
||||
**To migrate existing functions:** Update your handler to destructure from `event.body`, `event.queryStringParameters`, or `event.pathParameters` instead of directly from the params object.
|
||||
</Warning>
|
||||
|
||||
When a route trigger invokes your function, it receives a `RoutePayload` object that follows the AWS HTTP API v2 format. Import the type from `twenty-sdk`:
|
||||
|
||||
```typescript
|
||||
import { defineFunction, type RoutePayload } from 'twenty-sdk';
|
||||
|
||||
const handler = async (event: RoutePayload) => {
|
||||
// Access request data
|
||||
const { headers, queryStringParameters, pathParameters, body } = event;
|
||||
|
||||
// HTTP method and path are available in requestContext
|
||||
const { method, path } = event.requestContext.http;
|
||||
|
||||
return { message: 'Success' };
|
||||
};
|
||||
```
|
||||
|
||||
The `RoutePayload` type has the following structure:
|
||||
|
||||
| Property | Typ | Beschreibung |
|
||||
| ---------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------- |
|
||||
| `headers` | `Record<string, string \| undefined>` | HTTP headers (only those listed in `forwardedRequestHeaders`) |
|
||||
| `queryStringParameters` | `Record<string, string \| undefined>` | Query string parameters (multiple values joined with commas) |
|
||||
| `pathParameters` | `Record<string, string \| undefined>` | Path parameters extracted from the route pattern (e.g., `/users/:id` → `{ id: '123' }`) |
|
||||
| `inhalt` | `object \| null` | Parsed request body (JSON) |
|
||||
| `isBase64Encoded` | `boolesch` | Whether the body is base64 encoded |
|
||||
| `requestContext.http.method` | `string` | HTTP method (GET, POST, PUT, PATCH, DELETE) |
|
||||
| `requestContext.http.path` | `string` | Raw request path |
|
||||
|
||||
### Forwarding HTTP headers
|
||||
|
||||
By default, HTTP headers from incoming requests are **not** passed to your serverless function for security reasons. To access specific headers, explicitly list them in the `forwardedRequestHeaders` array:
|
||||
|
||||
```typescript
|
||||
export default defineFunction({
|
||||
universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
|
||||
name: 'webhook-handler',
|
||||
handler,
|
||||
triggers: [
|
||||
{
|
||||
universalIdentifier: 'c9f84c8d-b26d-40d1-95dd-4f834ae5a2c6',
|
||||
type: 'route',
|
||||
path: '/webhook',
|
||||
httpMethod: 'POST',
|
||||
isAuthRequired: false,
|
||||
forwardedRequestHeaders: ['x-webhook-signature', 'content-type'],
|
||||
},
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
In your handler, you can then access these headers:
|
||||
|
||||
```typescript
|
||||
const handler = async (event: RoutePayload) => {
|
||||
const signature = event.headers['x-webhook-signature'];
|
||||
const contentType = event.headers['content-type'];
|
||||
|
||||
// Validate webhook signature...
|
||||
return { received: true };
|
||||
};
|
||||
```
|
||||
|
||||
<Note>
|
||||
Header names are normalized to lowercase. Access them using lowercase keys (for example, `event.headers['content-type']`).
|
||||
</Note>
|
||||
|
||||
Sie können neue Funktionen auf zwei Arten erstellen:
|
||||
|
||||
* **Generiert**: Führen Sie `yarn create-entity` aus und wählen Sie die Option zum Hinzufügen einer neuen Funktion. Dadurch wird eine Starterdatei mit Handler und Konfiguration erzeugt.
|
||||
* **Manuell**: Erstellen Sie eine neue `*.function.ts`-Datei und verwenden Sie `defineFunction()` nach demselben Muster.
|
||||
|
||||
### Generierter typisierter Client
|
||||
|
||||
Führen Sie yarn generate aus, um einen lokalen typisierten Client in generated/ basierend auf Ihrem Workspace-Schema zu erstellen. Verwenden Sie ihn in Ihren Funktionen:
|
||||
|
||||
```typescript
|
||||
import Twenty from './generated';
|
||||
@@ -534,34 +626,34 @@ const client = new Twenty();
|
||||
const { me } = await client.query({ me: { id: true, displayName: true } });
|
||||
```
|
||||
|
||||
The client is re-generated by `yarn generate`. Re-run after changing your objects and `yarn sync` or when onboarding to a new workspace.
|
||||
Der Client wird durch `yarn generate` erneut generiert. Führen Sie ihn nach Änderungen an Ihren Objekten und nach `yarn sync` bzw. beim Onboarding in einen neuen Workspace erneut aus.
|
||||
|
||||
#### Runtime credentials in serverless functions
|
||||
#### Laufzeit-Anmeldedaten in serverlosen Funktionen
|
||||
|
||||
When your function runs on Twenty, the platform injects credentials as environment variables before your code executes:
|
||||
Wenn Ihre Funktion auf Twenty läuft, injiziert die Plattform vor der Ausführung Ihres Codes Anmeldedaten als Umgebungsvariablen:
|
||||
|
||||
* `TWENTY_API_URL`: Base URL of the Twenty API your app targets.
|
||||
* `TWENTY_API_KEY`: Short‑lived key scoped to your application's default function role.
|
||||
* `TWENTY_API_URL`: Basis-URL der Twenty-API, auf die Ihre App abzielt.
|
||||
* `TWENTY_API_KEY`: Kurzlebiger Schlüssel, der auf die Standard-Funktionsrolle Ihrer Anwendung begrenzt ist.
|
||||
|
||||
Notizen:
|
||||
|
||||
* You do not need to pass URL or API key to the generated client. It reads `TWENTY_API_URL` and `TWENTY_API_KEY` from process.env at runtime.
|
||||
* The API key's permissions are determined by the role referenced in your `application.config.ts` via `functionRoleUniversalIdentifier`. This is the default role used by serverless functions of your application.
|
||||
* Applications can define roles to follow least‑privilege. Grant only the permissions your functions need, then point `functionRoleUniversalIdentifier` to that role's universal identifier.
|
||||
* Sie müssen dem generierten Client weder URL noch API-Schlüssel übergeben. Er liest `TWENTY_API_URL` und `TWENTY_API_KEY` zur Laufzeit aus process.env.
|
||||
* Die Berechtigungen des API-Schlüssels werden durch die Rolle bestimmt, auf die in Ihrer `application.config.ts` über `functionRoleUniversalIdentifier` verwiesen wird. Dies ist die Standardrolle, die von den serverlosen Funktionen Ihrer Anwendung verwendet wird.
|
||||
* Anwendungen können Rollen definieren, um das Least-Privilege-Prinzip einzuhalten. Gewähren Sie nur die Berechtigungen, die Ihre Funktionen benötigen, und verweisen Sie dann mit `functionRoleUniversalIdentifier` auf den universellen Bezeichner dieser Rolle.
|
||||
|
||||
### Hello World example
|
||||
### Hello-World-Beispiel
|
||||
|
||||
Explore a minimal, end-to-end example that demonstrates objects, functions, and multiple triggers [here](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/hello-world):
|
||||
Ein minimales End-to-End-Beispiel, das Objekte, Funktionen und mehrere Trigger demonstriert, finden Sie [hier](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/hello-world):
|
||||
|
||||
## Manual setup (without the scaffolder)
|
||||
## Manuelle Einrichtung (ohne Scaffolder)
|
||||
|
||||
While we recommend using `create-twenty-app` for the best getting-started experience, you can also set up a project manually. Do not install the CLI globally. Instead, add `twenty-sdk` as a local dependency and wire scripts in your package.json:
|
||||
Wir empfehlen zwar `create-twenty-app` für das beste Einstiegserlebnis, Sie können ein Projekt aber auch manuell einrichten. Installieren Sie die CLI nicht global. Fügen Sie stattdessen `twenty-sdk` als lokale Abhängigkeit hinzu und binden Sie Skripte in Ihrer package.json ein:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn add -D twenty-sdk
|
||||
```
|
||||
|
||||
Then add scripts like these:
|
||||
Fügen Sie dann Skripte wie diese hinzu:
|
||||
|
||||
```json filename="package.json"
|
||||
{
|
||||
@@ -578,13 +670,13 @@ Then add scripts like these:
|
||||
}
|
||||
```
|
||||
|
||||
Now you can run the same commands via Yarn, e.g. `yarn dev`, `yarn sync`, etc.
|
||||
Jetzt können Sie dieselben Befehle über Yarn ausführen, z. B. `yarn dev`, `yarn sync` usw.
|
||||
|
||||
## Fehlerbehebung
|
||||
|
||||
* Authentication errors: run `yarn auth` and ensure your API key has the required permissions.
|
||||
* Cannot connect to server: verify the API URL and that the Twenty server is reachable.
|
||||
* Types or client missing/outdated: run `yarn generate` and then `yarn dev`.
|
||||
* Dev mode not syncing: ensure `yarn dev` is running and that changes are not ignored by your environment.
|
||||
* Authentifizierungsfehler: Führen Sie `yarn auth` aus und stellen Sie sicher, dass Ihr API-Schlüssel die erforderlichen Berechtigungen hat.
|
||||
* Verbindung zum Server nicht möglich: Überprüfen Sie die API-URL und dass der Twenty-Server erreichbar ist.
|
||||
* Typen oder Client fehlen/veraltet: Führen Sie `yarn generate` und anschließend `yarn dev` aus.
|
||||
* Dev-Modus synchronisiert nicht: Stellen Sie sicher, dass `yarn dev` läuft und dass Änderungen von Ihrer Umgebung nicht ignoriert werden.
|
||||
|
||||
Discord Help Channel: https://discord.com/channels/1130383047699738754/1130386664812982322
|
||||
Discord-Hilfekanal: https://discord.com/channels/1130383047699738754/1130386664812982322
|
||||
|
||||
@@ -1,44 +1,44 @@
|
||||
---
|
||||
title: Webhooks
|
||||
description: Receive real-time notifications when events occur in your CRM.
|
||||
description: Erhalten Sie Benachrichtigungen in Echtzeit, wenn Ereignisse in Ihrem CRM auftreten.
|
||||
---
|
||||
|
||||
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.
|
||||
Webhooks übermitteln Daten in Echtzeit an Ihre Systeme, wenn Ereignisse in Twenty auftreten — kein Polling erforderlich. Verwenden Sie sie, um externe Systeme synchron zu halten, Automatisierungen auszulösen oder Benachrichtigungen zu senden.
|
||||
|
||||
## Webhook erstellen
|
||||
|
||||
1. Gehen Sie zu **Einstellungen → APIs & Webhooks → Webhooks**
|
||||
2. Klicken Sie auf **+ Webhook erstellen**
|
||||
3. Enter your webhook URL (must be publicly accessible)
|
||||
3. Geben Sie Ihre Webhook-URL ein (muss öffentlich zugänglich sein)
|
||||
4. Klicken Sie auf **Speichern**
|
||||
|
||||
The webhook activates immediately and starts sending notifications.
|
||||
Der Webhook wird sofort aktiviert und beginnt, Benachrichtigungen zu senden.
|
||||
|
||||
<VimeoEmbed videoId="928786708" title="Creating a webhook" />
|
||||
<VimeoEmbed videoId="928786708" title="Webhook erstellen" />
|
||||
|
||||
### Webhooks verwalten
|
||||
|
||||
**Edit**: Click the webhook → Update URL → **Save**
|
||||
**Bearbeiten**: Klicken Sie auf den Webhook → URL aktualisieren → **Speichern**
|
||||
|
||||
**Delete**: Click the webhook → **Delete** → Confirm
|
||||
**Löschen**: Klicken Sie auf den Webhook → **Löschen** → Bestätigen
|
||||
|
||||
## Ereignisse
|
||||
|
||||
Twenty sends webhooks for these event types:
|
||||
Twenty sendet Webhooks für diese Ereignistypen:
|
||||
|
||||
| Ereignis | Beispiel |
|
||||
| ------------------ | ---------------------------------------------------------- |
|
||||
| **Record Created** | `person.created`, `company.created`, `note.created` |
|
||||
| **Record Updated** | `person.updated`, `company.updated`, `opportunity.updated` |
|
||||
| **Record Deleted** | `person.deleted`, `company.deleted` |
|
||||
| Ereignis | Beispiel |
|
||||
| -------------------------- | ---------------------------------------------------------- |
|
||||
| **Datensatz erstellt** | `person.created`, `company.created`, `note.created` |
|
||||
| **Datensatz aktualisiert** | `person.updated`, `company.updated`, `opportunity.updated` |
|
||||
| **Datensatz gelöscht** | `person.deleted`, `company.deleted` |
|
||||
|
||||
All event types are sent to your webhook URL. Event filtering may be added in future releases.
|
||||
Alle Ereignistypen werden an Ihre Webhook-URL gesendet. Eine Ereignisfilterung kann in zukünftigen Versionen hinzugefügt werden.
|
||||
|
||||
## Payload Format
|
||||
## Payload-Format
|
||||
|
||||
Each webhook sends an HTTP POST with a JSON body:
|
||||
Jeder Webhook sendet eine HTTP-POST-Anfrage mit einem JSON-Body:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -55,35 +55,35 @@ Each webhook sends an HTTP POST with a JSON body:
|
||||
}
|
||||
```
|
||||
|
||||
| Feld | Beschreibung |
|
||||
| ------------- | ------------------------------------------------ |
|
||||
| `ereignis` | What happened (e.g., `person.created`) |
|
||||
| `daten` | The full record that was created/updated/deleted |
|
||||
| `zeitstempel` | When the event occurred (UTC) |
|
||||
| Feld | Beschreibung |
|
||||
| ------------- | -------------------------------------------------------------------- |
|
||||
| `ereignis` | Was passiert ist (z. B. `person.created`) |
|
||||
| `daten` | Der vollständige Datensatz, der erstellt/aktualisiert/gelöscht wurde |
|
||||
| `zeitstempel` | Wann das Ereignis auftrat (UTC) |
|
||||
|
||||
<Note>
|
||||
Respond with a **2xx HTTP status** (200-299) to acknowledge receipt. Non-2xx responses are logged as delivery failures.
|
||||
Antworten Sie mit einem **2xx-HTTP-Status** (200-299), um den Empfang zu bestätigen. Nicht-2xx-Antworten werden als Zustellfehler protokolliert.
|
||||
</Note>
|
||||
|
||||
## Webhook-Validierung
|
||||
|
||||
Twenty signs each webhook request for security. Validate signatures to ensure requests are authentic.
|
||||
Twenty signiert jede Webhook-Anfrage zu Sicherheitszwecken. Validieren Sie die Signaturen, um sicherzustellen, dass die Anfragen authentisch sind.
|
||||
|
||||
### Headers
|
||||
### Header
|
||||
|
||||
| Kopfzeile | Beschreibung |
|
||||
| ---------------------------- | --------------------- |
|
||||
| `X-Twenty-Webhook-Signature` | HMAC SHA256 signature |
|
||||
| `X-Twenty-Webhook-Timestamp` | Request timestamp |
|
||||
| Kopfzeile | Beschreibung |
|
||||
| ---------------------------- | ----------------------- |
|
||||
| `X-Twenty-Webhook-Signature` | HMAC-SHA256-Signatur |
|
||||
| `X-Twenty-Webhook-Timestamp` | Zeitstempel der Anfrage |
|
||||
|
||||
### Validation Steps
|
||||
### Validierungsschritte
|
||||
|
||||
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`
|
||||
1. Den Zeitstempel aus `X-Twenty-Webhook-Timestamp` abrufen
|
||||
2. Zeichenfolge erstellen: `{timestamp}:{JSON payload}`
|
||||
3. Den HMAC-SHA256-Hash mit Ihrem Webhook-Geheimnis berechnen
|
||||
4. Mit `X-Twenty-Webhook-Signature` vergleichen
|
||||
|
||||
### Example (Node.js)
|
||||
### Beispiel (Node.js)
|
||||
|
||||
```javascript
|
||||
const crypto = require("crypto");
|
||||
@@ -103,10 +103,10 @@ const isValid = expectedSignature === req.headers["x-twenty-webhook-signature"];
|
||||
|
||||
## Webhooks vs Workflows
|
||||
|
||||
| Methode | Richtung | 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 |
|
||||
| Methode | Richtung | Anwendungsfall |
|
||||
| ---------------------------- | -------- | -------------------------------------------------------------------------------- |
|
||||
| **Webhooks** | OUT | Externe Systeme automatisch über jede Datensatzänderung benachrichtigen |
|
||||
| **Workflow + HTTP-Anfrage** | OUT | Daten mit benutzerdefinierter Logik (Filter, Transformationen) nach außen senden |
|
||||
| **Workflow-Webhook-Trigger** | IN | Daten aus externen Systemen in Twenty empfangen |
|
||||
|
||||
For receiving external data, see [Set Up a Webhook Trigger](/l/de/user-guide/workflows/how-tos/connect-to-other-tools/set-up-a-webhook-trigger).
|
||||
Für den Empfang externer Daten siehe [Webhook-Trigger einrichten](/l/de/user-guide/workflows/how-tos/connect-to-other-tools/set-up-a-webhook-trigger).
|
||||
|
||||
Reference in New Issue
Block a user