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

> Crie, gerencie e inspecione assinaturas de webhook pela CLI

Os webhooks enviam eventos em tempo real do Social media studio para o seu servidor. Use estes comandos para gerenciar assinaturas, enviar entregas de teste, revisar os logs de entrega e tentar novamente tentativas com falha, sem sair do terminal.

> [!NOTE]
>
> Os limites de webhook por plano (máximo de assinaturas, retenção de logs) são aplicados no servidor. Veja a [Visão geral de Webhooks](/pt-BR/webhooks/overview.md) para a matriz completa de limites e a referência de templates de payload.

> [!NOTE]
>
> Todos os comandos abaixo respeitam as flags globais: `--json` (padrão) ou `--table` para o formato de saída, `--verbose` para logs extras e `--api-key <key>` / `--api-url <url>` para substituir as credenciais (também configuráveis pelas variáveis de ambiente `SOME_API_KEY` e `SOME_API_URL`).

## webhooks:create

Cria uma nova assinatura de webhook.

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

| Opção | Descrição |
| - | - |
| `--url <url>` | Endpoint HTTPS que receberá as entregas **(obrigatório)** |
| `--categories <csv>` | Categorias separadas por vírgula: `post`, `draft`, `approval`, `social`, `media`, `composer`, `analytics`, `inbox`, `biolink`, `ai`, `team`, `organization`, `account`, `auth`, `api_key`, `webhook`, `integration`, `subscription`, `support`, `template`, `referral`, `mcp`, `quota` **(obrigatório)** |
| `--events <csv>` | Nomes de eventos separados por vírgula, para um controle mais fino (subconjunto das categorias) |
| `--description <text>` | Rótulo legível |
| `--payload-template <json>` | Template de corpo JSON personalizado com as variáveis `{{event}}`, `{{category}}`, `{{timestamp}}`, `{{data}}` |

```bash Exemplos theme={null}
# Mínimo: assinar todos os eventos de post
so-me webhooks:create \
  --url https://example.com/hooks/some \
  --categories post

# Assinar várias categorias
so-me webhooks:create \
  --url https://example.com/hooks/some \
  --categories post,inbox,approval \
  --description "Production endpoint"

# Assinar somente eventos específicos (mais restrito que as categorias)
so-me webhooks:create \
  --url https://example.com/hooks/some \
  --categories post \
  --events post.published,post.failed

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

# Template de payload adequado para o Slack, a partir de um arquivo
so-me webhooks:create \
  --url https://hooks.slack.com/services/xxx \
  --categories inbox \
  --payload-template "$(cat ./slack-template.json)"
```

> [!TIP]
>
> A resposta inclui um valor `secret` exibido uma única vez. Guarde-o: ele é usado para verificar os cabeçalhos `X-Webhook-Signature` das entregas recebidas e só é retornado na criação.

## webhooks:list

Lista todas as assinaturas de webhook do espaço de trabalho atual.

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

```bash Exemplos theme={null}
# Saída JSON padrão
so-me webhooks:list

# Tabela formatada
so-me webhooks:list --table

# Encadear com jq: somente endpoints ativos
so-me webhooks:list | jq '.[] | select(.isActive == true) | {id, url, categories}'

# Contar as assinaturas
so-me webhooks:list | jq 'length'
```

## webhooks:get

Busca uma única assinatura pelo ID, incluindo seu estado atual e os contadores de falhas.

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

```bash Exemplos theme={null}
# Detalhes completos em JSON
so-me webhooks:get 550e8400-e29b-41d4-a716-446655440000

# Verificar somente a URL e o status
so-me webhooks:get 550e8400-... | jq '{url, isActive, consecutiveFailures}'
```

## webhooks:update

Atualiza qualquer campo de uma assinatura existente. Somente os campos informados são modificados.

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

| Opção | Descrição |
| - | - |
| `--url <url>` | Altera a URL do endpoint |
| `--categories <csv>` | Substitui as categorias assinadas |
| `--events <csv>` | Substitui os eventos assinados |
| `--description <text>` | Atualiza o rótulo |
| `--payload-template <json>` | Substitui o template de payload |
| `--active` | Ativa a assinatura (define `isActive: true`) |
| `--inactive` | Desativa a assinatura (define `isActive: false` e interrompe as entregas) |
| `--regenerate-secret` | Rotaciona o segredo de assinatura (invalida o anterior) |

> [!NOTE]
>
> Pelo menos um campo deve ser informado, caso contrário o comando termina com erro. `--active` e `--inactive` são mutuamente exclusivas; passar as duas também gera erro.

```bash Exemplos theme={null}
# Alterar a URL do endpoint
so-me webhooks:update 550e8400-... \
  --url https://new.example.com/hooks/some

# Trocar as categorias assinadas
so-me webhooks:update 550e8400-... \
  --categories post,inbox,media

# Restringir a eventos específicos
so-me webhooks:update 550e8400-... \
  --events post.published,post.failed,inbox.message_received

# Desativar um endpoint temporariamente
so-me webhooks:update 550e8400-... --inactive

# Reativá-lo depois
so-me webhooks:update 550e8400-... --active

# Rotacionar o segredo de assinatura (as assinaturas antigas se tornam inválidas)
so-me webhooks:update 550e8400-... --regenerate-secret

# Atualizar o rótulo e o template de payload juntos
so-me webhooks:update 550e8400-... \
  --description "Staging endpoint" \
  --payload-template '{"event":"{{event}}","data":{{data}}}'

# Combinar várias atualizações em uma única chamada
so-me webhooks:update 550e8400-... \
  --url https://new.example.com/hooks/some \
  --categories post,approval \
  --active
```

> [!WARNING]
>
> `--regenerate-secret` invalida imediatamente o segredo anterior. O novo segredo é retornado na resposta da atualização; atualize o seu código de verificação para usá-lo antes de fazer a rotação em produção.

## webhooks:delete

Remove uma assinatura permanentemente. Nenhuma outra entrega será tentada.

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

```bash Exemplos theme={null}
# Remover uma assinatura
so-me webhooks:delete 550e8400-e29b-41d4-a716-446655440000

# Remover todas as assinaturas inativas em um único pipeline
so-me webhooks:list \
  | jq -r '.[] | select(.isActive == false) | .id' \
  | xargs -I {} so-me webhooks:delete {}
```

## webhooks:test

Enfileira uma entrega sintética `webhook.test` para verificar se o seu endpoint está acessível e se a verificação de assinatura funciona.

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

```bash Exemplos theme={null}
# Disparar um teste em uma assinatura conhecida
so-me webhooks:test 550e8400-e29b-41d4-a716-446655440000

# Testar todas as assinaturas ativas de uma só vez
so-me webhooks:list \
  | jq -r '.[] | select(.isActive == true) | .id' \
  | xargs -I {} so-me webhooks:test {}
```

> [!TIP]
>
> O payload de teste sempre usa o nome de evento `webhook.test` e a categoria `test`, independentemente das categorias configuradas na assinatura. Isso permite que o seu endpoint trate rapidamente o tráfego sintético.

## webhooks:deliveries

Lista as tentativas de entrega recentes (sucessos e falhas) com paginação.

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

| Opção | Descrição |
| - | - |
| `--page <number>` | Número da página (padrão: 1) |
| `--limit <number>` | Itens por página (padrão: 20) |

```bash Exemplos theme={null}
# As 20 entregas mais recentes
so-me webhooks:deliveries

# Próxima página
so-me webhooks:deliveries --page 2

# Página maior, em tabela
so-me webhooks:deliveries --limit 100 --table

# Somente as que falharam
so-me webhooks:deliveries --limit 100 \
  | jq '.data[] | select(.status != "success")'

# Contar as falhas na página mais recente
so-me webhooks:deliveries --limit 100 \
  | jq '[.data[] | select(.status != "success")] | length'
```

## webhooks:retry

Recoloca na fila uma entrega que falhou anteriormente. Usa a assinatura, o evento e o payload originais.

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

```bash Exemplos theme={null}
# Tentar novamente uma entrega pelo ID do log
so-me webhooks:retry 7c2d4e8f-1a2b-3c4d-5e6f-7890abcdef12

# Tentar novamente todas as entregas com falha da última página
so-me webhooks:deliveries --limit 100 \
  | jq -r '.data[] | select(.status == "failed") | .id' \
  | xargs -I {} so-me webhooks:retry {}
```

> [!WARNING]
>
> Tentar novamente uma entrega cuja assinatura foi excluída retorna um erro. Se não tiver certeza, verifique antes com `webhooks:get`.

## webhooks:events

Lista todos os nomes de eventos compatíveis com a API, agrupados por categoria. Útil para montar filtros de `--events` ou validar a configuração da sua assinatura. A resposta é um array de objetos `{ category, label, events }`.

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

```bash Exemplos theme={null}
# Catálogo completo em JSON
so-me webhooks:events

# Como tabela
so-me webhooks:events --table

# Somente os eventos da caixa de entrada
so-me webhooks:events | jq '.[] | select(.category == "inbox") | .events'

# Lista simples com todos os nomes de eventos
so-me webhooks:events | jq -r '.[].events[]'

# Contar os eventos por categoria
so-me webhooks:events | jq 'map({category, count: (.events | length)})'
```

> **[Payloads e verificação de assinatura](/pt-BR/webhooks/payloads.md)**
>
> Veja exemplos de payload de cada categoria de evento e aprenda a verificar o cabeçalho `X-Webhook-Signature`.


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