Webhooks

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.

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 para a matriz completa de limites e a referência de templates de payload.

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.

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

Exemplos

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

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.

so-me webhooks:list

Exemplos

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

so-me webhooks:get <id>

Exemplos

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

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)

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.

Exemplos

# 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

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

so-me webhooks:delete <id>

Exemplos

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

so-me webhooks:test <id>

Exemplos

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

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.

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)

Exemplos

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

so-me webhooks:retry <delivery-id>

Exemplos

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

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

so-me webhooks:events

Exemplos

# 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

Veja exemplos de payload de cada categoria de evento e aprenda a verificar o cabeçalho X-Webhook-Signature.

Primeiros passos

Publicação

AI Studio

Caixa de entrada e engajamento

Análises

Biolink

Equipe e colaboração

Configurações e cobrança

Suporte

Webhooks

webhooks:create

webhooks:list

webhooks:get

webhooks:update

webhooks:delete

webhooks:test

webhooks:deliveries

webhooks:retry

webhooks:events

Payloads e verificação de assinatura

​webhooks:create

​webhooks:list

​webhooks:get

​webhooks:update

​webhooks:delete

​webhooks:test

​webhooks:deliveries

​webhooks:retry

​webhooks:events

Payloads e verificação de assinatura

webhooks:create

webhooks:list

webhooks:get

webhooks:update

webhooks:delete

webhooks:test

webhooks:deliveries

webhooks:retry

webhooks:events