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

> Crea, gestiona e inspecciona suscripciones de webhooks desde la CLI

Los webhooks envían eventos en tiempo real de Social media studio a tu servidor. Usa estos comandos para gestionar suscripciones, enviar entregas de prueba, revisar los registros de entrega y reintentar intentos fallidos sin salir de tu terminal.

> [!NOTE]
>
> Los límites de webhooks de tu plan (máximo de suscripciones, retención de registros) se aplican en el servidor. Consulta el [resumen de webhooks](/es/webhooks/overview.md) para ver la matriz completa de límites y la referencia de plantillas de carga.

> [!NOTE]
>
> Todos los comandos siguientes respetan las opciones globales: `--json` (por defecto) o `--table` para el formato de salida, `--verbose` para registro adicional y `--api-key <key>` / `--api-url <url>` para sustituir las credenciales (también configurables con las variables de entorno `SOME_API_KEY` y `SOME_API_URL`).

## webhooks:create

Crea una suscripción de webhook nueva.

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

| Opción | Descripción |
| - | - |
| `--url <url>` | Endpoint HTTPS que recibirá las entregas **(obligatorio)** |
| `--categories <csv>` | Categorías separadas por comas: `post`, `draft`, `approval`, `social`, `media`, `composer`, `analytics`, `inbox`, `biolink`, `ai`, `team`, `organization`, `account`, `auth`, `api_key`, `webhook`, `integration`, `subscription`, `support`, `template`, `referral`, `mcp`, `quota` **(obligatorio)** |
| `--events <csv>` | Nombres de eventos separados por comas para un control más fino (subconjunto de las categorías) |
| `--description <text>` | Etiqueta legible |
| `--payload-template <json>` | Plantilla JSON personalizada del cuerpo con las variables `{{event}}`, `{{category}}`, `{{timestamp}}`, `{{data}}` |

```bash Ejemplos theme={null}
# 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)"
```

> [!TIP]
>
> La respuesta incluye un valor `secret` de un solo uso. Guárdalo: se usa para verificar las cabeceras `X-Webhook-Signature` de las entregas entrantes y solo se devuelve al crear la suscripción.

## webhooks:list

Lista todas las suscripciones de webhook del espacio de trabajo actual.

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

```bash Ejemplos theme={null}
# 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

Obtiene una suscripción por ID, incluidos su estado actual y los contadores de fallos.

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

```bash Ejemplos theme={null}
# 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

Actualiza cualquier campo de una suscripción existente. Solo se modifican los campos que indiques.

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

| Opción | Descripción |
| - | - |
| `--url <url>` | Cambia la URL del endpoint |
| `--categories <csv>` | Sustituye las categorías suscritas |
| `--events <csv>` | Sustituye los eventos suscritos |
| `--description <text>` | Actualiza la etiqueta |
| `--payload-template <json>` | Sustituye la plantilla de carga |
| `--active` | Activa la suscripción (establece `isActive: true`) |
| `--inactive` | Desactiva la suscripción (establece `isActive: false` y detiene las entregas) |
| `--regenerate-secret` | Rota el secreto de firma (invalida el anterior) |

> [!NOTE]
>
> Debe indicarse al menos un campo o el comando termina con un error. `--active` y `--inactive` son mutuamente excluyentes: pasar ambos también produce un error.

```bash Ejemplos theme={null}
# 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
```

> [!WARNING]
>
> `--regenerate-secret` invalida de inmediato el secreto anterior. El nuevo secreto se devuelve en la respuesta de la actualización: actualiza tu código de verificación para usarlo antes de rotarlo en producción.

## webhooks:delete

Elimina una suscripción de forma permanente. No se intentan más entregas.

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

```bash Ejemplos theme={null}
# 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

Pone en cola una entrega sintética `webhook.test` para verificar que tu endpoint es accesible y que la verificación de la firma funciona.

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

```bash Ejemplos theme={null}
# 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 {}
```

> [!TIP]
>
> La carga de prueba siempre usa el nombre de evento `webhook.test` y la categoría `test`, independientemente de las categorías configuradas en la suscripción. Así tu endpoint puede dar vía rápida al tráfico sintético.

## webhooks:deliveries

Lista los intentos de entrega recientes (tanto éxitos como fallos) con paginación.

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

| Opción | Descripción |
| - | - |
| `--page <number>` | Número de página (por defecto: 1) |
| `--limit <number>` | Elementos por página (por defecto: 20) |

```bash Ejemplos theme={null}
# 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

Vuelve a poner en cola una entrega fallida anterior. Usa la suscripción, el evento y la carga originales.

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

```bash Ejemplos theme={null}
# 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 {}
```

> [!WARNING]
>
> Reintentar una entrega cuya suscripción se ha eliminado devolverá un error. Si tienes dudas, consulta primero `webhooks:get`.

## webhooks:events

Lista todos los nombres de eventos que admite la API, agrupados por categoría. Útil para construir filtros de `--events` o validar la configuración de tu suscripción. La respuesta es un arreglo de objetos `{ category, label, events }`.

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

```bash Ejemplos theme={null}
# 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)})'
```

> **[Cargas y verificación de firmas](/es/webhooks/payloads.md)**
>
> Consulta cargas de ejemplo de cada categoría de eventos y aprende a verificar la cabecera `X-Webhook-Signature`.


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