1. Home
  2. Dokumente
  3. Handbuch
  4. Expertenwissen
  5. Webhooks
Drucken

Webhooks

Verfügbar in SeaTable Free, Plus und Enterprise

SeaTable bietet die Möglichkeit für eine Base einen oder mehrere Webhooks einzurichten. Sobald ein Webhook eingerichtet ist, löst jede Änderung an den Inhalten einer Base einen Impuls in Form eines HTTP-Post Requests aus.

Vereinfacht kann man sich einen Webhook wie ein Benachrichtigungssystem vorstellen. Jedes Mal, wenn sich in einer Base etwas ändert, wird ein Datensatz an eine von Ihnen definierte URL geschickt.

  • Sie fügen eine neue Zeile hinzu: SeaTable schickt Ihnen eine Nachricht.
  • Sie setzen den Haken in einer Checkbox, auch das ist eine Nachricht.

Jede noch so kleine Änderung an den Inhalten einer Base führt dazu, dass ein Webhook verschickt wird. Wichtig: bei Änderungen an der Struktur der Base wird kein Webhook verschickt.

Mögliche Einsatzzwecke von Webhooks

Webhooks sind neben REST-APIs eine beliebte Methode, um IT-Systeme miteinander sprechen zu lassen. Ein Webhook ist gewissermaßen eine Art umgedrehter API-Request. Bei der API wartet SeaTable darauf, dass eine Anfrage kommt, die von der API beantwortet wird. Bei einem Webhook hingegen wird automatisch eine Benachrichtigung verschickt, wenn etwas passiert.

Webhooks funktionieren somit grundsätzlich nur in eine Richtung. SeaTable teilt einer anderen Anwendung mit, dass etwas passiert ist. Es liegt somit in der Verantwortung der Zielanwendung zu entscheiden, ob diese Änderung relevant ist und welche Folgeaktivitäten ausgelöst werden sollen. Beliebte Einsatzzwecke von Webhooks sind z.B.:

  • E-Mail oder Chat-Benachrichtigung, sobald eine neue Zeile in einer Base angelegt wird
  • Automatische Veröffentlichung eines Artikels, sobald der Status z.B. auf „jetzt veröffentlichen“ geändert wird
  • Aktualisierung eines Abos, sobald eine Bezahlung erfasst wird

Im Sinne einer Automation sind Webhooks somit immer die auslösenden Trigger, die zu einer gewünschten Folgeaktivität führen.

Einen Webhook einrichten

Fahren Sie auf der Startseite von cloud.seatable.io über eine Base für die Sie einen Webhook einrichten wollen. Im Kontextmenü unter Erweitert finden Sie den Punkt Webhooks. Um einen neuen Webhook anzulegen, genügt es einfach eine beliebige URL anzugeben. Der geheime Schlüssel darf auch leer bleiben, wenn jedoch Ihre Ziel-URL öffentlich verfügbar ist, sollten Sie diesen Wert setzen und bei der Verarbeitung der Webhooks diesen Wert validieren. Sobald Sie den Webhook speichern, wird jede inhaltliche Änderung Ihrer Base an diese URL geschickt.

Formular zum Erzeugen eines Webhooks in SeaTable

Formular zum Erzeugen eines Webhooks in SeaTable

Folgende Änderungen triggern einen Webhook:

  • neue Zeile wird hinzugefügt oder dupliziert
  • Zeile wird gelöscht
  • Zeileninhalt wird verändert

Strukturelle Veränderungen an einer Base wie das Hinzufügen einer neuen Spalte, ein Spaltenkommentar, das Anlegen einer neuen Ansicht oder eine Zeilensperrung triggert keinen Webhook.

Beispiele von Webhooks, die SeaTable verschickt

Beispiel 1: eine neue Zeile wurde hinzugefügt (z.B. im SeaTable Webinterface, per Webformular oder per API-Call)

{
  "event": "update",
  "data": {
    "dtable_uuid": "fae0a3a42ba94df88e8303fd385e37de",
    "row_id": "Fk-i7xZGS5iA5aSvaG5HAA",
    "op_user": "4bc9a7c79c5942c5b6238413f2132bea@auth.local",
    "op_type": "insert_row",
    "op_time": 1649922777.279,
    "table_id": "9g8f",
    "table_name": "Opportunities",
    "row_name": "",
    "row_data": []
  }
}

Beispiel 2: ein Single-Select Wert wurde ausgewählt

{
  "event": "update",
  "data": {
    "dtable_uuid": "fae0a3a42ba94df88e8303fd385e37de",
    "row_id": "QoNno3QiTF26sxmG1sl3_g",
    "op_user": "4bc9a7c79c5942c5b6238413f2132bea@auth.local",
    "op_type": "modify_row",
    "op_time": 1649929622.589,
    "table_id": "9g8f",
    "table_name": "Opportunities",
    "row_name": "", "row_data": [{
      "column_key": "589r",
      "column_name": "Prio",
      "column_type": "single-select",
      "column_data": {
        "options": [{
          "name": "++",
          "color": "#F4667C",
          "textColor": "#FFFFFF",
          "id": "381992"
        },
        {
          "name": "+",
          "color": "#FBD44A",
          "textColor": "#FFFFFF",
          "id": "830278"
        }
      ]}, 
      "value": "381992",
      "old_value": ""
    }]
  }
}

Beispiel 3: eine Zeile wurde gelöscht

{
  "event": "update",
  "data": {
    "dtable_uuid": "fae0a3a42ba94df88e8303fd385e37de",
    "row_id": "QoNno3QiTF26sxmG1sl3_g",
    "op_user": "4bc9a7c79c5942c5b6238413f2132bea@auth.local",
    "op_type": "delete_row",
    "op_time": 1649929650.668,
    "table_id": "9g8f",
    "table_name": "Opportunities",
    "row_name": "",
    "row_data": []
  }
}

Mögliche Werte, die ein Webhook annehmen kann

Der Wert „event“ ist aktuell immer update.
Der Wert „data“ hat immer die folgende Struktur:

{
      "dtable_uuid": base_uuid,
      "row_id": row_id,
      "op_user": username (or user_id),
      "op_type": op_type,  // insert_row, delete_row, delete_rows, modify_row, modify_rows
      "op_time": op_time,
      "table_id": table_id,
      "table_name": table_name,
      "row_name": row_name,
      "row_data": row_data,
      "op_app": appName  // If the base has been updated via API Token, then the op_app will be the app's name of that API
}

Beispiel für eine einfache Verarbeitung eines Webhooks mit PHP

Die Verarbeitung eines Webhooks erfolgt je nach Programmiersprache unterschiedlich. Der folgende PHP-Code dient lediglich zur Veranschaulichung, wie man z.B. auf ein gewisses Ereignis wie z.B. eine gelöschte Zeile reagieren kann.

$raw_payload = file_get_contents('php://input', true);
$payload = json_decode($raw_payload, true);

if($payload['event'] === "update"){

    // check for a deleted row
    if($payload['data']['op_type'] === "delete_row"){
        // ...
    }
    
    // check if a checkbox was checked in the column with the name "checkbox"
    if($payload['data']['row_data'][0]['column_name'] === "checkbox" AND $payload['data']['row_data'][0]['value'] === true){
        // ...
    }

    // save content to file (for debugging
    $file = 'webhook_payload.txt';
    $current = file_get_contents($file);
    $current .= $raw_payload;
    $output = file_put_contents($file, $current);
}