# Webhooks, Zapier und Make

> Sende Ereignisse deiner Boards – neue Karten, Verschiebungen, erledigte Karten, Kommentare, Statusmeldungen – an deinen eigenen Server, an Zapier oder Make. Zustellungen sind signiert und enthalten nur IDs; ein Protokoll zeigt jede, fehlgeschlagene lassen sich erneut senden.

Source: https://contals.com/docs/de/integrations/webhooks/  
Last updated: 2026-10-16

Ein Webhook schickt, was auf deinen Boards passiert, an eine Adresse im Internet: deinen eigenen Server, einen **Zapier**-Zap oder ein **Make**-Szenario. Jede Zustellung ist ein signierter `POST` und enthält nur IDs – keine Titel, keine Texte. Der Empfänger liest die Details über die [API](/docs/de/ai/api/) mit seinem eigenen Token; was dieses Token sehen darf, entscheidet, was er sieht.

**Wer sie einrichtet:** Board-Admins für ihr Board; Owner und Admins eines Workspace für jedes Board, das der ganze Workspace sieht. Ein privates Board braucht einen eigenen Webhook, eingerichtet von seinen Admins. **Vertrauliche Boards senden nie etwas.**

## Einen Webhook einrichten

1. Öffne die Seite der Webhooks: auf der Seite der Workspace-Einstellungen (dein Avatar → der Workspace) → **Webhooks, Zapier und Make** → **Webhooks**; für ein Board: Board-Kopf → **Einstellungen** → **Webhooks dieses Boards**.
2. **Webhook hinzufügen**: ein **Name** (für Menschen), die **Adresse (URL)**, **Welche Boards** – **Jedes Board, das der ganze Workspace sieht** oder **Ein Board** – und die **Ereignisse**.
3. **Webhook speichern**. Kopiere jetzt das **Signatur-Geheimnis** – es wird nur einmal gezeigt. Dein Empfänger prüft damit jede Zustellung.
4. Öffne den Webhook und wähle **Test-Ereignis senden**; das **Zustellprotokoll** zeigt, ob es angekommen ist.

Die Adresse muss `https` auf dem üblichen Port sein, auf einem öffentlichen Host. Adressen in privaten Netzen (`10.x`, `192.168.x`, `localhost`, link-lokale Adressen und Metadaten-Adressen von Cloud-Anbietern, auch IPv6 und Namen, die dorthin zeigen) werden abgelehnt – beim Speichern und bei jeder Zustellung wieder. Weiterleitungen werden nicht befolgt. Adresse und Geheimnis werden verschlüsselt gespeichert; die Seite zeigt nur den Host und die letzten vier Zeichen.

## Zapier und Make

- **Zapier:** Lege einen Zap mit dem Auslöser **Webhooks by Zapier** → **Catch Hook** an, kopiere seine Adresse und füge sie in Contals als Adresse des Webhooks ein.
- **Make:** Lege ein Szenario mit **Webhooks** → **Custom webhook** an, kopiere seine Adresse und füge sie in Contals ein.
- Um mit dem Ereignis etwas zu tun, lies die Karte in einem weiteren Schritt über die Contals-API (zum Beispiel in Zapier mit **Webhooks by Zapier** → **GET** und `Authorization: Bearer <token>`, mit `links.card` aus der Zustellung).

Contals-Apps für beide sind auf unserer Seite bereit und warten auf ihre Aufnahme in die Verzeichnisse von Zapier und Make. Sie verbinden sich mit einem [persönlichen API-Token](/docs/de/ai/api/#anmeldung) mit den Scopes `read`, `write` und `admin`, abonnieren von selbst, wenn du einen Zap oder ein Szenario einschaltest, kündigen das Abo, wenn du ihn ausschaltest, und ergänzen die Karte, den Kommentar oder die Statusmeldung für dich. So angelegte Abos erscheinen auf der Seite der Webhooks wie alle anderen, markiert mit Zapier oder Make.

## Ereignisse

| Ereignis | Wann |
|---|---|
| `card.created` | Eine Karte wird erstellt |
| `card.updated` | Titel oder Beschreibung einer Karte ändern sich |
| `card.moved` | Eine Karte kommt in eine andere Liste |
| `card.completed` / `card.reopened` | Eine Karte wird erledigt / wieder offen |
| `card.archived` / `card.restored` | Eine Karte wird archiviert / wiederhergestellt |
| `card.assignees_changed` | Personen kommen auf eine Karte oder gehen |
| `card.labels_changed` | Die Labels einer Karte ändern sich |
| `card.due_date_changed` | Eine Karte bekommt eine neue Fälligkeit (oder verliert sie); `data` enthält `dueDate` und `previousDueDate` (Kalenderdaten), `dueAt` und `previousDueAt` (die Uhrzeit als Zeitpunkt, oder null, wenn ganztägig), `startDate` und `startAt` |
| `comment.added` | Jemand kommentiert eine Karte |
| `checklist_item.completed` | Ein Checklistenpunkt ist erledigt |
| `list.created` / `list.archived` | Eine Liste wird erstellt / archiviert |
| `status.posted` | Ein Board bekommt eine Statusmeldung |
| `webhook.test` | **Test-Ereignis senden** (wird immer zugestellt) |

Änderungen durch Importe, Kopien zwischen Boards und Contals selbst bleiben still; Änderungen über die API, durch Automatisierungen und auf öffentlichen Seiten senden Ereignisse.

## Eine Zustellung

```http
POST /deine/adresse HTTP/1.1
Content-Type: application/json
User-Agent: Contals-Webhooks/1.0
webhook-id: itg_01jq8m6g1hm5b7e9g1j3m5p7r9:v42
webhook-timestamp: 1792137600
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

{
  "id": "itg_01jq8m6g1hm5b7e9g1j3m5p7r9:v42",
  "type": "card.created",
  "format": "contals-webhook/1",
  "occurredAt": "2026-10-16T08:00:00.000Z",
  "workspaceId": "wsp_01jq8m1v7hb2f5j9m3q7t1w5y9",
  "boardId": "brd_01jq8m2x9kd4h7n1p3s5v7w9y1",
  "boardVersion": 42,
  "actor": { "type": "person", "id": "usr_01jq8m0t5f9z3d7h1k5n9r3v7x" },
  "data": { "cardId": "crd_01jq8m3a5bf9w8x0e2r4t6y8z0", "listId": "lst_01jq8m2zz4c8g2k6m0q4t8w2a6" },
  "links": {
    "board": "https://app.contals.com/api/public/v1/boards/brd_01jq8m2x9kd4h7n1p3s5v7w9y1",
    "card": "https://app.contals.com/api/public/v1/boards/brd_01jq8m2x9kd4h7n1p3s5v7w9y1/cards/crd_01jq8m3a5bf9w8x0e2r4t6y8z0",
    "lists": "https://app.contals.com/api/public/v1/boards/brd_01jq8m2x9kd4h7n1p3s5v7w9y1/lists"
  }
}
```

- `id` ist bei jedem Versuch derselben Zustellung gleich: Damit erkennst du Wiederholungen.
- `actor.type` ist `person`, `automation`, `guest` (eine öffentliche Seite) oder `system`.
- Hole die Details aus `links` mit deinem eigenen Token. Ein Board, das das Token nicht öffnen darf, antwortet mit `404`.

## Die Signatur prüfen

Die Header folgen [Standard Webhooks](https://www.standardwebhooks.com/): `webhook-signature` enthält `v1,<Signatur>` – ein HMAC-SHA256 in Base64 über `<webhook-id>.<webhook-timestamp>.<Body>` mit den Bytes deines Geheimnisses nach `whsec_` (Base64). Lehne Zustellungen ab, deren Zeitstempel älter als fünf Minuten ist.

```js
import { createHmac, timingSafeEqual } from 'node:crypto'

function verify(secret, headers, rawBody) {
  const id = headers['webhook-id'], ts = headers['webhook-timestamp']
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64')
  const expected = Buffer.from(createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest('base64'))
  return headers['webhook-signature'].split(' ').some((part) => {
    const sig = Buffer.from(part.replace(/^v1,/, ''))
    return sig.length === expected.length && timingSafeEqual(sig, expected)
  })
}
```

**Neues Signatur-Geheimnis** auf der Seite des Webhooks erstellt ein neues Geheimnis, das einmal gezeigt wird. 24 Stunden lang signieren beide jede Zustellung (der Header enthält dann zwei Signaturen), damit dein Empfänger ohne Lücke umstellen kann.

## Wiederholungen, Protokoll und Ausschalten

- Antworte innert 10 Sekunden mit einem Status `2xx`. Zeitüberschreitungen, `429` und `5xx` werden mit wachsenden Pausen wiederholt – nach 30 Sekunden, 2 und 10 Minuten, einer halben Stunde, 1, 3, 6 und 12 Stunden –, insgesamt etwa einen Tag lang; danach ist die Zustellung **Aufgegeben**.
- Andere `4xx`-Antworten und Weiterleitungen werden nicht wiederholt. `410 Gone` schaltet den Webhook sofort aus (so antwortet Zapier für einen ausgeschalteten Zap).
- Nach 10 fehlgeschlagenen Zustellungen in Folge schaltet sich der Webhook selbst aus, und die Person, der er gehört, bekommt eine E-Mail mit einem Link zum Zustellprotokoll. Schalte ihn auf seiner Seite wieder ein, sobald der Empfänger funktioniert – das setzt die Fehler zurück und macht dich zur Eigentümerin oder zum Eigentümer.
- Das **Zustellprotokoll** behält die letzten 100 Zustellungen der letzten 30 Tage mit Status, HTTP-Code, Versuchen und Inhalt. Fehlgeschlagene, aufgegebene und übersprungene Zustellungen lassen sich **Erneut senden**.
- Ein Webhook, dessen Eigentümer seine Boards nicht mehr verwalten kann, schaltet sich selbst aus. Wird sein Board vertraulich, sendet er nichts mehr; du kannst ihn noch ausschalten oder löschen.

## Limits

| | Gratis | Team | Business |
|---|---|---|---|
| Webhooks pro Organisation | 2 | 25 | 100 |
| Zustellungen pro Tag | 500 | 10’000 | 50’000 |

Ein Board kann höchstens 10 Webhooks haben. Zustellungen über dem Tageslimit werden übersprungen und im Protokoll markiert. Abos von Zapier und Make zählen als Webhooks.

## Für Entwickler: REST-Hooks

Zapier, Make und deine eigenen Werkzeuge verwalten Abos über die API mit einem Token mit dem Scope `admin` (ein Abo ist Konfiguration, wie das Teilen eines Boards):

- `POST /api/public/v1/webhooks` mit `url`, `events` und entweder `boardId` oder `workspaceId` (und optional `name`) – die Antwort enthält das Abo und sein `secret`, das einzige Mal, dass es gezeigt wird.
- `GET /api/public/v1/webhooks?workspaceId=…` – die Abos, die du verwaltest (nie die Adresse oder das Geheimnis).
- `DELETE /api/public/v1/webhooks/{webhookId}` – das Abo kündigen.

Anlegen, Ändern, ein neues Geheimnis, erneutes Senden und Löschen stehen im [Audit-Log](/docs/de/settings/audit-log/).

## Siehe auch

- [API und MCP-Server](/docs/de/ai/api/) – Tokens, Scopes und alle Operationen
- [Chat-Benachrichtigungen](/docs/de/power-ups/integrations/) – Ereignisse eines Boards als lesbare Nachrichten in Slack, Teams, Google Chat oder Discord
- [Kalender-Abos](/docs/de/views/across-boards/) – Fälligkeiten in deiner Kalender-App