> ## Documentation Index
> Fetch the complete documentation index at: https://docs.so-me.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Webhook-Abonnements in der CLI erstellen, verwalten und prüfen

Webhooks übermitteln Echtzeit-Events von Social media studio an deinen Server. Mit diesen Befehlen verwaltest du Abonnements, sendest Test-Zustellungen, prüfst Zustellungsprotokolle und wiederholst fehlgeschlagene Versuche, ohne dein Terminal zu verlassen.

> [!NOTE]
>
> Tariflimits für Webhooks (maximale Abonnements, Protokollaufbewahrung) werden serverseitig durchgesetzt. Die vollständige Limit-Matrix und die Referenz zu Payload-Vorlagen findest du in der [Webhooks-Übersicht](/de/webhooks/overview.md).

> [!NOTE]
>
> Jeder der folgenden Befehle berücksichtigt die globalen Flags: `--json` (Standard) oder `--table` für das Ausgabeformat, `--verbose` für zusätzliche Protokollierung sowie `--api-key <key>` / `--api-url <url>`, um Zugangsdaten zu überschreiben (ebenfalls über die Umgebungsvariablen `SOME_API_KEY` und `SOME_API_URL` konfigurierbar).

## webhooks:create

Erstellt ein neues Webhook-Abonnement.

```bash theme={null}
so-me webhooks:create --url <url> --categories <csv> [options]
```

| Option | Beschreibung |
| - | - |
| `--url <url>` | HTTPS-Endpunkt, der die Zustellungen empfängt **(erforderlich)** |
| `--categories <csv>` | Kommagetrennte Kategorien: `post`, `draft`, `approval`, `social`, `media`, `composer`, `analytics`, `inbox`, `biolink`, `ai`, `team`, `organization`, `account`, `auth`, `api_key`, `webhook`, `integration`, `subscription`, `support`, `template`, `referral`, `mcp`, `quota` **(erforderlich)** |
| `--events <csv>` | Kommagetrennte Event-Namen für feinere Steuerung (Teilmenge der Kategorien) |
| `--description <text>` | Lesbare Bezeichnung |
| `--payload-template <json>` | Eigene JSON-Body-Vorlage mit den Variablen `{{event}}`, `{{category}}`, `{{timestamp}}`, `{{data}}` |

```bash Beispiele theme={null}
# Minimal — alle Beitrags-Events abonnieren
so-me webhooks:create \
  --url https://example.com/hooks/some \
  --categories post

# Mehrere Kategorien abonnieren
so-me webhooks:create \
  --url https://example.com/hooks/some \
  --categories post,inbox,approval \
  --description "Production endpoint"

# Nur bestimmte Events abonnieren (enger als Kategorien)
so-me webhooks:create \
  --url https://example.com/hooks/some \
  --categories post \
  --events post.published,post.failed

# Discord-taugliche Payload-Vorlage
so-me webhooks:create \
  --url https://discord.com/api/webhooks/xxx/yyy \
  --categories post,approval \
  --payload-template '{"content":"🚀 {{event}} at {{timestamp}}"}'

# Slack-taugliche Payload-Vorlage aus einer Datei
so-me webhooks:create \
  --url https://hooks.slack.com/services/xxx \
  --categories inbox \
  --payload-template "$(cat ./slack-template.json)"
```

> [!TIP]
>
> Die Antwort enthält einen einmaligen `secret`-Wert. Speichere ihn — er dient zur Verifizierung der `X-Webhook-Signature`-Header eingehender Zustellungen und wird nur beim Erstellen zurückgegeben.

## webhooks:list

Listet alle Webhook-Abonnements im aktuellen Workspace auf.

```bash theme={null}
so-me webhooks:list
```

```bash Beispiele theme={null}
# Standard-JSON-Ausgabe
so-me webhooks:list

# Formatierte Tabelle
so-me webhooks:list --table

# An jq weiterleiten — nur aktive Endpunkte
so-me webhooks:list | jq '.[] | select(.isActive == true) | {id, url, categories}'

# Abonnements zählen
so-me webhooks:list | jq 'length'
```

## webhooks:get

Ruft ein einzelnes Abonnement über seine ID ab, einschließlich seines aktuellen Zustands und seiner Fehlerzähler.

```bash theme={null}
so-me webhooks:get <id>
```

```bash Beispiele theme={null}
# Alle Details als JSON
so-me webhooks:get 550e8400-e29b-41d4-a716-446655440000

# Nur URL und Status prüfen
so-me webhooks:get 550e8400-... | jq '{url, isActive, consecutiveFailures}'
```

## webhooks:update

Aktualisiert beliebige Felder eines bestehenden Abonnements. Nur die Felder, die du angibst, werden geändert.

```bash theme={null}
so-me webhooks:update <id> [options]
```

| Option | Beschreibung |
| - | - |
| `--url <url>` | Die Endpunkt-URL ändern |
| `--categories <csv>` | Die abonnierten Kategorien ersetzen |
| `--events <csv>` | Die abonnierten Events ersetzen |
| `--description <text>` | Die Bezeichnung aktualisieren |
| `--payload-template <json>` | Die Payload-Vorlage ersetzen |
| `--active` | Das Abonnement aktivieren (setzt `isActive: true`) |
| `--inactive` | Das Abonnement deaktivieren (setzt `isActive: false`, stoppt Zustellungen) |
| `--regenerate-secret` | Das Signatur-Secret rotieren (macht das alte ungültig) |

> [!NOTE]
>
> Mindestens ein Feld muss angegeben werden, sonst beendet sich der Befehl mit einem Fehler. `--active` und `--inactive` schließen sich gegenseitig aus — werden beide angegeben, gibt es ebenfalls einen Fehler.

```bash Beispiele theme={null}
# Endpunkt-URL ändern
so-me webhooks:update 550e8400-... \
  --url https://new.example.com/hooks/some

# Kategorie-Abonnements austauschen
so-me webhooks:update 550e8400-... \
  --categories post,inbox,media

# Auf bestimmte Events eingrenzen
so-me webhooks:update 550e8400-... \
  --events post.published,post.failed,inbox.message_received

# Einen Endpunkt vorübergehend deaktivieren
so-me webhooks:update 550e8400-... --inactive

# Ihn später wieder aktivieren
so-me webhooks:update 550e8400-... --active

# Das Signatur-Secret rotieren (alte Signaturen werden ungültig)
so-me webhooks:update 550e8400-... --regenerate-secret

# Bezeichnung und Payload-Vorlage gemeinsam aktualisieren
so-me webhooks:update 550e8400-... \
  --description "Staging endpoint" \
  --payload-template '{"event":"{{event}}","data":{{data}}}'

# Mehrere Änderungen in einem Aufruf kombinieren
so-me webhooks:update 550e8400-... \
  --url https://new.example.com/hooks/some \
  --categories post,approval \
  --active
```

> [!WARNING]
>
> `--regenerate-secret` macht das bisherige Secret sofort ungültig. Das neue Secret wird in der Update-Antwort zurückgegeben — passe deinen Verifizierungscode an, bevor du es in der Produktion rotierst.

## webhooks:delete

Entfernt ein Abonnement dauerhaft. Es werden keine weiteren Zustellungen versucht.

```bash theme={null}
so-me webhooks:delete <id>
```

```bash Beispiele theme={null}
# Ein Abonnement entfernen
so-me webhooks:delete 550e8400-e29b-41d4-a716-446655440000

# Alle inaktiven Abonnements in einer Pipeline entfernen
so-me webhooks:list \
  | jq -r '.[] | select(.isActive == false) | .id' \
  | xargs -I {} so-me webhooks:delete {}
```

## webhooks:test

Stellt eine synthetische `webhook.test`-Zustellung in die Warteschlange, um zu prüfen, ob dein Endpunkt erreichbar ist und deine Signaturverifizierung funktioniert.

```bash theme={null}
so-me webhooks:test <id>
```

```bash Beispiele theme={null}
# Einen Test gegen ein bekanntes Abonnement auslösen
so-me webhooks:test 550e8400-e29b-41d4-a716-446655440000

# Alle aktiven Abonnements auf einmal testen
so-me webhooks:list \
  | jq -r '.[] | select(.isActive == true) | .id' \
  | xargs -I {} so-me webhooks:test {}
```

> [!TIP]
>
> Die Test-Payload verwendet unabhängig von den konfigurierten Kategorien des Abonnements immer den Event-Namen `webhook.test` und die Kategorie `test`. So kann dein Endpunkt synthetischen Traffic auf dem schnellen Pfad behandeln.

## webhooks:deliveries

Listet die letzten Zustellungsversuche (Erfolge und Fehlschläge) mit Paginierung auf.

```bash theme={null}
so-me webhooks:deliveries [options]
```

| Option | Beschreibung |
| - | - |
| `--page <number>` | Seitennummer (Standard: 1) |
| `--limit <number>` | Einträge pro Seite (Standard: 20) |

```bash Beispiele theme={null}
# Die letzten 20 Zustellungen
so-me webhooks:deliveries

# Nächste Seite
so-me webhooks:deliveries --page 2

# Größere Seite als Tabelle
so-me webhooks:deliveries --limit 100 --table

# Nur die fehlgeschlagenen
so-me webhooks:deliveries --limit 100 \
  | jq '.data[] | select(.status != "success")'

# Fehlschläge auf der letzten Seite zählen
so-me webhooks:deliveries --limit 100 \
  | jq '[.data[] | select(.status != "success")] | length'
```

## webhooks:retry

Stellt eine zuvor fehlgeschlagene Zustellung erneut in die Warteschlange. Verwendet das ursprüngliche Abonnement, das ursprüngliche Event und die ursprüngliche Payload.

```bash theme={null}
so-me webhooks:retry <delivery-id>
```

```bash Beispiele theme={null}
# Eine einzelne Zustellung anhand ihrer Protokoll-ID wiederholen
so-me webhooks:retry 7c2d4e8f-1a2b-3c4d-5e6f-7890abcdef12

# Jede fehlgeschlagene Zustellung der letzten Seite wiederholen
so-me webhooks:deliveries --limit 100 \
  | jq -r '.data[] | select(.status == "failed") | .id' \
  | xargs -I {} so-me webhooks:retry {}
```

> [!WARNING]
>
> Das Wiederholen einer Zustellung, deren Abonnement gelöscht wurde, liefert einen Fehler. Prüfe vorher mit `webhooks:get`, wenn du unsicher bist.

## webhooks:events

Listet jeden von der API unterstützten Event-Namen auf, gruppiert nach Kategorie. Nützlich, um `--events`-Filter zu bauen oder deine Abonnementkonfiguration zu validieren. Die Antwort ist ein Array von `{ category, label, events }`-Objekten.

```bash theme={null}
so-me webhooks:events
```

```bash Beispiele theme={null}
# Vollständiger Katalog als JSON
so-me webhooks:events

# Als Tabelle
so-me webhooks:events --table

# Nur die Posteingangs-Events
so-me webhooks:events | jq '.[] | select(.category == "inbox") | .events'

# Flache Liste aller Event-Namen
so-me webhooks:events | jq -r '.[].events[]'

# Events pro Kategorie zählen
so-me webhooks:events | jq 'map({category, count: (.events | length)})'
```

> **[Payloads und Signaturverifizierung](/de/webhooks/payloads.md)**
>
> Sieh dir Beispiel-Payloads für jede Event-Kategorie an und erfahre, wie du den Header `X-Webhook-Signature` verifizierst.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.