Webhooks

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.

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.

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.

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

Beispiele

# 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)"

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.

so-me webhooks:list

Beispiele

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

so-me webhooks:get <id>

Beispiele

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

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)

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.

Beispiele

# 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

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

so-me webhooks:delete <id>

Beispiele

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

so-me webhooks:test <id>

Beispiele

# 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 {}

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.

so-me webhooks:deliveries [options]

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

Beispiele

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

so-me webhooks:retry <delivery-id>

Beispiele

# 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 {}

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.

so-me webhooks:events

Beispiele

# 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

Sieh dir Beispiel-Payloads für jede Event-Kategorie an und erfahre, wie du den Header X-Webhook-Signature verifizierst.

Erste Schritte

Veröffentlichen

AI Studio

Posteingang und Interaktion

Analysen

Biolink

Team und Zusammenarbeit

Einstellungen und Abrechnung

Support

Webhooks

webhooks:create

webhooks:list

webhooks:get

webhooks:update

webhooks:delete

webhooks:test

webhooks:deliveries

webhooks:retry

webhooks:events

Payloads und Signaturverifizierung

​webhooks:create

​webhooks:list

​webhooks:get

​webhooks:update

​webhooks:delete

​webhooks:test

​webhooks:deliveries

​webhooks:retry

​webhooks:events

Payloads und Signaturverifizierung

webhooks:create

webhooks:list

webhooks:get

webhooks:update

webhooks:delete

webhooks:test

webhooks:deliveries

webhooks:retry

webhooks:events