Webhooks, Zapier und Make

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 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

Ö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.
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.
Webhook speichern. Kopiere jetzt das Signatur-Geheimnis – es wird nur einmal gezeigt. Dein Empfänger prüft damit jede Zustellung.
Ö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 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

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: 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.

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.

Siehe auch

API und MCP-Server – Tokens, Scopes und alle Operationen
Chat-Benachrichtigungen – Ereignisse eines Boards als lesbare Nachrichten in Slack, Teams, Google Chat oder Discord
Kalender-Abos – Fälligkeiten in deiner Kalender-App