Webhooks

Webhooks push real-time events from Social media studio to your server. Use these commands to manage subscriptions, send test deliveries, review delivery logs, and retry failed attempts without leaving your terminal.

Webhook plan limits (max subscriptions, log retention) are enforced server-side. See Webhooks Overview for the full limits matrix and payload templating reference.

Every command below honors the global flags: --json (default) or --table for output format, --verbose for extra logging, and --api-key <key> / --api-url <url> to override credentials (also configurable via the SOME_API_KEY and SOME_API_URL environment variables).

webhooks:create

Create a new webhook subscription.

so-me webhooks:create --url <url> --categories <csv> [options]

Option	Description
`--url <url>`	HTTPS endpoint to receive deliveries (required)
`--categories <csv>`	Comma-separated categories: `post`, `draft`, `approval`, `social`, `media`, `composer`, `analytics`, `inbox`, `biolink`, `ai`, `team`, `organization`, `account`, `auth`, `api_key`, `webhook`, `integration`, `subscription`, `support`, `template`, `referral`, `mcp`, `quota` (required)
`--events <csv>`	Comma-separated event names for fine-grained control (subset of categories)
`--description <text>`	Human-readable label
`--payload-template <json>`	Custom JSON body template with `{{event}}`, `{{category}}`, `{{timestamp}}`, `{{data}}` variables

Examples

# Minimal — subscribe to all post events
so-me webhooks:create \
  --url https://example.com/hooks/some \
  --categories post

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

# Subscribe to specific events only (narrower than categories)
so-me webhooks:create \
  --url https://example.com/hooks/some \
  --categories post \
  --events post.published,post.failed

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

# Slack-friendly payload template from a file
so-me webhooks:create \
  --url https://hooks.slack.com/services/xxx \
  --categories inbox \
  --payload-template "$(cat ./slack-template.json)"

The response includes a one-time secret value. Store it — it’s used to verify X-Webhook-Signature headers on incoming deliveries and is only returned at creation.

webhooks:list

List all webhook subscriptions in the current workspace.

so-me webhooks:list

Examples

# Default JSON output
so-me webhooks:list

# Formatted table
so-me webhooks:list --table

# Pipe to jq — only active endpoints
so-me webhooks:list | jq '.[] | select(.isActive == true) | {id, url, categories}'

# Count subscriptions
so-me webhooks:list | jq 'length'

webhooks:get

Fetch a single subscription by ID, including its current state and failure counters.

so-me webhooks:get <id>

Examples

# Full details as JSON
so-me webhooks:get 550e8400-e29b-41d4-a716-446655440000

# Check just the URL and status
so-me webhooks:get 550e8400-... | jq '{url, isActive, consecutiveFailures}'

webhooks:update

Update any field on an existing subscription. Only the fields you pass are modified.

so-me webhooks:update <id> [options]

Option	Description
`--url <url>`	Change the endpoint URL
`--categories <csv>`	Replace the subscribed categories
`--events <csv>`	Replace the subscribed events
`--description <text>`	Update the label
`--payload-template <json>`	Replace the payload template
`--active`	Activate the subscription (sets `isActive: true`)
`--inactive`	Deactivate the subscription (sets `isActive: false`, stops deliveries)
`--regenerate-secret`	Rotate the signing secret (invalidates the old one)

At least one field must be supplied or the command exits with an error. --active and --inactive are mutually exclusive — passing both also errors out.

Examples

# Change endpoint URL
so-me webhooks:update 550e8400-... \
  --url https://new.example.com/hooks/some

# Swap category subscriptions
so-me webhooks:update 550e8400-... \
  --categories post,inbox,media

# Narrow down to specific events
so-me webhooks:update 550e8400-... \
  --events post.published,post.failed,inbox.message_received

# Temporarily disable an endpoint
so-me webhooks:update 550e8400-... --inactive

# Re-enable it later
so-me webhooks:update 550e8400-... --active

# Rotate the signing secret (old signatures become invalid)
so-me webhooks:update 550e8400-... --regenerate-secret

# Update label and payload template together
so-me webhooks:update 550e8400-... \
  --description "Staging endpoint" \
  --payload-template '{"event":"{{event}}","data":{{data}}}'

# Combine multiple updates in one call
so-me webhooks:update 550e8400-... \
  --url https://new.example.com/hooks/some \
  --categories post,approval \
  --active

--regenerate-secret immediately invalidates the previous secret. The new secret is returned in the update response — update your verification code to use it before rotating in production.

webhooks:delete

Permanently remove a subscription. No further deliveries are attempted.

so-me webhooks:delete <id>

Examples

# Remove a subscription
so-me webhooks:delete 550e8400-e29b-41d4-a716-446655440000

# Remove every inactive subscription in one pipeline
so-me webhooks:list \
  | jq -r '.[] | select(.isActive == false) | .id' \
  | xargs -I {} so-me webhooks:delete {}

webhooks:test

Queue a synthetic webhook.test delivery to verify your endpoint is reachable and your signature verification works.

so-me webhooks:test <id>

Examples

# Fire a test against a known subscription
so-me webhooks:test 550e8400-e29b-41d4-a716-446655440000

# Test every active subscription at once
so-me webhooks:list \
  | jq -r '.[] | select(.isActive == true) | .id' \
  | xargs -I {} so-me webhooks:test {}

The test payload always uses event name webhook.test and category test, regardless of the subscription’s configured categories. This lets your endpoint fast-path synthetic traffic.

webhooks:deliveries

List recent delivery attempts (both successes and failures) with pagination.

so-me webhooks:deliveries [options]

Option	Description
`--page <number>`	Page number (default: 1)
`--limit <number>`	Items per page (default: 20)

Examples

# Recent 20 deliveries
so-me webhooks:deliveries

# Next page
so-me webhooks:deliveries --page 2

# Larger page as a table
so-me webhooks:deliveries --limit 100 --table

# Only the failed ones
so-me webhooks:deliveries --limit 100 \
  | jq '.data[] | select(.status != "success")'

# Count failures in the most recent page
so-me webhooks:deliveries --limit 100 \
  | jq '[.data[] | select(.status != "success")] | length'

webhooks:retry

Re-queue a previously failed delivery. Uses the original subscription, event, and payload.

so-me webhooks:retry <delivery-id>

Examples

# Retry a single delivery by its log ID
so-me webhooks:retry 7c2d4e8f-1a2b-3c4d-5e6f-7890abcdef12

# Retry every failed delivery from the last page
so-me webhooks:deliveries --limit 100 \
  | jq -r '.data[] | select(.status == "failed") | .id' \
  | xargs -I {} so-me webhooks:retry {}

Retrying a delivery whose subscription has been deleted will return an error. Check webhooks:get first if you’re unsure.

webhooks:events

List every event name the API supports, grouped by category. Useful for building --events filters or validating your subscription configuration. The response is an array of { category, label, events } objects.

so-me webhooks:events

Examples

# Full catalog as JSON
so-me webhooks:events

# As a table
so-me webhooks:events --table

# Only the inbox events
so-me webhooks:events | jq '.[] | select(.category == "inbox") | .events'

# Flat list of all event names
so-me webhooks:events | jq -r '.[].events[]'

# Count events per category
so-me webhooks:events | jq 'map({category, count: (.events | length)})'

Payloads & signature verification

See example payloads for every event category and learn how to verify the X-Webhook-Signature header.

Getting Started

Publishing

AI Studio

Inbox & Engagement

Analytics

Biolink

Team & Collaboration

Settings & Billing

Support

Webhooks

webhooks:create

webhooks:list

webhooks:get

webhooks:update

webhooks:delete

webhooks:test

webhooks:deliveries

webhooks:retry

webhooks:events

Payloads & signature verification

​webhooks:create

​webhooks:list

​webhooks:get

​webhooks:update

​webhooks:delete

​webhooks:test

​webhooks:deliveries

​webhooks:retry

​webhooks:events

Payloads & signature verification

webhooks:create

webhooks:list

webhooks:get

webhooks:update

webhooks:delete

webhooks:test

webhooks:deliveries

webhooks:retry

webhooks:events