Configurar um webhook do SOAR

Compatível com:

Google SecOps SOAR

Os webhooks são uma solução leve para ingerir alertas da sua organização na plataforma SOAR do Google Security Operations.

Os alertas ingeridos por webhook aparecem na plataforma com as mesmas informações dos alertas ingeridos usando conectores.

O Google recomenda usar um conector ou um webhook da mesma origem, mas não os dois, para evitar a criação de casos duplicados.

Os webhooks são mais adequados para cenários que exigem uma lógica de mapeamento básica, enquanto os conectores são melhores para mapeamento avançado e flexível.

Configurar um webhook para ingerir alertas

Para configurar um webhook e ingerir alertas, siga estas etapas:

1. Acesse Configurações do SOAR > Ingestão > Webhooks.
2. Clique em Adicionar Adicionar webhook de entrada.
3. Insira um nome para o novo webhook e escolha um ambiente.
4. Clique em Salvar. Depois de salvar, o novo webhook vai aparecer na página principal.
5. Copie o URL do webhook e anote para uso posterior. Você precisa inserir esse endereço na plataforma de origem como o destino do webhook.

Observação: o URL do webhook aparece depois que você salva. Copie esse URL imediatamente, porque ele não vai mais aparecer depois que você sair da página. Você precisa desse URL para configurar o destino do webhook na plataforma de origem. Se você salvar sem copiar o URL, clique em em cache Gerar novo URL para criar um.

Dados do mapa

Depois de fazer upload de um exemplo de JSON, use a seção Mapeamento de dados para mapear campos do JSON de origem para os campos adequados no SOAR do Google Security Operations. O sistema processa seu JSON bruto, e você usa a interface do usuário (UI) para estabelecer os mapeamentos.

1. Na seção Mapeamento de dados, clique em Fazer upload de uma amostra JSON. Forneça uma amostra representativa do payload JSON enviado pelo webhook.
2. Mapeie os campos do Google Security Operations com os campos correspondentes na sua amostra JSON. Por exemplo, para mapear o campo obrigatório StartTime, selecione um campo de carimbo de data/hora do JSON, como Detections.Last.Update.
3. Use o criador de expressões para refinar os dados. Por exemplo, use a função Formato de data para converter o carimbo de data/hora no formato de milissegundos da época Unix necessário. Para mais informações, consulte Usar o Criador de expressões.
4. Clique em Executar no Criador de expressões para testar o mapeamento e conferir o resultado. Uma marca de seleção verde indica um mapeamento bem-sucedido.
5. O payload JSON do webhook precisa conter os campos obrigatórios para criação de casos e ingestão de alertas. Para mais detalhes, consulte Entender o esquema JSON do webhook.
6. Depois de mapear todos os campos necessários, clique em Salvar e ative o webhook.

Entender os campos de destino do mapeamento

Ao mapear seus dados JSON, você está mapeando para campos padronizados no SOAR do Google Security Operations. Esses campos são organizados em categorias para ajudar você a normalizar e estruturar os dados recebidos. Os campos disponíveis na UI de mapeamento de dados são baseados na ontologia do sistema interno. As principais categorias incluem:

• Campos de entidade:use esses campos para pontos de dados de que o sistema pode extrair e modelar entidades automaticamente, como endereços IP, nomes de domínio, hashes de arquivo e nomes de usuário. O mapeamento desses campos enriquece o alerta e melhora a correlação e a rotação.
• Campos de eventos genéricos:use-os para metadados gerais de eventos, como carimbos de data/hora (StartTime, EndTime), descrições ou mensagens de eventos e outros atributos comuns de eventos.
• Metadados técnicos e de dispositivo:use esses campos para detalhes técnicos sobre a origem do evento, como o fornecedor e o produto do dispositivo de geração de relatórios (DeviceVendor, DeviceProduct), a gravidade do evento e outros atributos técnicos semelhantes.

Explore os campos disponíveis na ferramenta de mapeamento de dados na interface do usuário do SOAR do Google Security Operations para encontrar o campo de destino mais adequado para cada dado no seu payload JSON.

Entender o esquema JSON do webhook

Para garantir que seus alertas sejam ingeridos e processados corretamente pelo SOAR do Google Security Operations, o payload JSON do webhook precisa seguir uma estrutura específica. As tabelas a seguir detalham os principais campos esperados no payload JSON.

Principais campos de casos e alertas

Esses campos representam as propriedades de nível superior do alerta ou caso que está sendo criado.

Campo	Tipo	Formato recomendado	Obrigatório	Descrição	Exemplo
TicketId	String	UUID	Sim	Um identificador globalmente exclusivo (GUID, na sigla em inglês) interno para um caso na plataforma SOAR. O requisito de exclusividade de TicketId é condicional e depende de DisplayId: Se um DisplayId exclusivo for fornecido, o TicketId não precisará ser exclusivo. Se DisplayId não for fornecido, o TicketId precisará ser exclusivo. O TicketId geralmente tem o mesmo valor que o DisplayId.	"f7167971-f641-432f-a06f-ebca3caaa9dd"
SourceSystemName	String	Texto	Sim	O nome do sistema externo (por exemplo, SIEM ou um sistema de detecção e resposta de endpoints [EDR]) que enviou os alertas originais para o SOAR.	"Splunk"
Name	String	Texto	Sim	O título ou nome do caso, geralmente extraído do tipo ou resumo do alerta de origem.	"Suspicious Login Attempt"
DeviceVendor	String	Texto	Sim	O fornecedor do dispositivo ou produto que gerou o alerta. Isso também pode ser mapeado com base nos dados de eventos.	"Palo Alto Networks"
RuleGenerator	String	Texto	Sim	O nome da regra no sistema de origem (por exemplo, uma regra de correlação do SIEM) que gerou o alerta.	"Brute Force Attempt Detected"
StartTime	String ou número inteiro	Milissegundos da época (UTC) ou string ISO8601 (por exemplo, "2026-04-09T14:30:00Z")	Sim	O horário de início do evento mais antigo no caso. Se você fornecer um número inteiro, ele precisa estar em milissegundos da época Unix.	1670000000000 ou "2026-04-09T14:30:00Z"
Environment	String	Texto	Não	O nome do ambiente SOAR a que este alerta pertence. Ele precisa corresponder a um ambiente definido nas configurações do SOAR.	"Default Environment"
Description	String	Texto	Não	Uma breve descrição do caso ou alerta.	"Failed login followed by success from new IP"
DisplayId	String	UUID ou String	Não	Um identificador usado para fins de exibição na interface do SOAR. Esse campo é a chave primária que o sistema verifica para detectar alertas duplicados. Um alerta é rejeitado como duplicado se o DisplayId não for exclusivo. Essa verificação de exclusividade em DisplayId tem precedência sobre TicketId. O DisplayId geralmente tem o mesmo valor que o TicketId.	"f7167971-f641-432f-a06f-ebca3caaa9dd"
Reason	String	Texto	Não	O motivo da criação ou do acionamento do alerta.	"Unusual file access patterns detected."
DeviceProduct	String	Texto	Não	O nome do produto do fornecedor que gerou o alerta. Isso também pode ser mapeado com base nos dados de eventos.	"Cortex XDR"
EndTime	String ou número inteiro	Milissegundos da época (UTC) ou string ISO8601 (por exemplo, "2026-04-09T14:30:00Z")	Não	O horário de término do evento mais recente no caso. Se você fornecer um número inteiro, ele precisa estar em milissegundos da época Unix.	1670000060000 ou "2026-04-09T14:31:00Z"
Priority	Número inteiro	0 a 100	Não	O nível de prioridade do caso. O padrão é 40 se não for informado. (0 a 19: informativa, 20 a 39: baixa, 40 a 59: média, 60 a 79: alta, 80 a 100: crítica)	80
EventsList	Matriz	Matriz de objetos JSON	Não	Uma matriz que contém um ou mais objetos de evento brutos recebidos da fonte. Consulte Enviar dados de eventos brutos.	[ { ... }, { ... } ]
EventProduct	String	Texto	Não	Produto que criou os eventos.	"Cortex XDR"
EventName	String	Texto	Não	O título ou nome do evento, geralmente extraído do tipo ou resumo do alerta de origem.	"Suspicious Login Attempt"

Como enviar dados de eventos brutos: a matriz EventsList

Envie o payload JSON bruto que representa os eventos conforme eles vêm do sistema de origem na matriz EventsList. Esse objeto é um elemento na matriz EventsList. Em seguida, mapeie campos como source_ip e timestamp usando a UI de mapeamento de dados.

Exemplo de objeto de evento na matriz EventsList

{
  "event_id": "9a8b7c-1234-5678",
  "timestamp": "2026-07-01T07:29:50Z",
  "signature": "UserLoginFailed",
  "severity": "Medium",
  "user_name": "administrator",
  "source_ip": "192.168.1.50",
  "destination_ip": "10.0.0.10",
  "domain": "CORP",
  "status": "Failure",
  "Reason": "Wrong Password",
  "EventProduct": "Acme Firewall",
  "EventName": "Failed Login Attempt"
}

Principais considerações e práticas recomendadas

• Carimbos de data/hora:use milissegundos da época Unix para todos os campos StartTime e EndTime no nível superior (como um número inteiro). Nos dados de eventos, forneça os carimbos de data/hora como estão na origem. Você os converte na UI do mapeamento de dados.
• Campos obrigatórios:verifique se todos os campos marcados como "Sim" na coluna "Obrigatório" estão presentes no payload JSON.
• Matriz EventsList:essa matriz é crucial. Mesmo que o alerta represente um único evento, ele precisa ser envolvido na matriz EventsList.
• Interface de mapeamento de dados:use a ferramenta de mapeamento de dados na UI de configuração de webhook para mapear campos do JSON bruto para os campos adequados do SOAR do Google Security Operations.
• Unicidade:DisplayId precisa ser exclusivo para cada novo alerta e evitar a remoção de duplicidades. TicketId precisa ser exclusivo se DisplayId não for fornecido.
• Teste:use as guias Fazer upload de amostra JSON e Teste na página Configuração de webhook no SOAR para validar a estrutura e os mapeamentos do payload.

Observação sobre a exibição do carimbo de data/hora do evento:ao ingerir dados de eventos usando webhooks, a exibição dos campos de carimbo de data/hora na lista de detalhes do alerta pode variar. A plataforma tenta formatar campos que parecem estar relacionados ao tempo, supondo que o valor seja fornecido em milissegundos de época. Se um campo de carimbo de data/hora (geralmente um que contém "time" no nome, como "@timestamp") for enviado em um formato diferente de milissegundos de época (por exemplo, "MM/DD/YYYY HH:MM:SS" ou "YYYY-MM-DDTHH:MM:SSz"), a visualização em lista poderá não mostrar a hora como esperado. Isso acontece porque o sistema tenta interpretar como milissegundos desde o período. Para conferir o valor original e bruto enviado no webhook, clique duas vezes no campo de carimbo de data/hora na lista de eventos. Para ter resultados de exibição mais consistentes em toda a plataforma, configure o sistema de origem para enviar valores de tempo em milissegundos de época sempre que possível ou verifique se a conversão está correta na UI de mapeamento de dados.

Testar o webhook

Na guia Teste, é possível testar a funcionalidade de ponta a ponta do webhook e conferir descrições detalhadas dos erros.

1. Na guia Teste, copie o URL do webhook.
2. Faça upload de um arquivo JSON com os dados relevantes.
3. Clique em Executar. Os resultados aparecem junto com a saída.

Configurar a plataforma CrowdStrike

Este caso de uso mostra as etapas no CrowdStrike para que o webhook comece a ingerir alertas na plataforma do Google SecOps.

1. No painel do CrowdStrike Falcon, acesse a Falcon Store e instale o complemento Webhooks.
2. Configure o webhook com o nome e o URL que você copiou da plataforma do Google SecOps e clique em Salvar.
3. Acesse a seção Fluxos de trabalho.
4. Clique em Criar um fluxo de trabalho.
5. Selecione um gatilho, como Nova detecção, e clique em Próxima.
6. Selecione Adicionar ação.
7. Na seção Personalizar ação, selecione Notificações no menu Tipo de ação e Chamar webhook no menu Ação.
8. Selecione o nome que você adicionou na etapa inicial e todos os campos necessários e clique em Concluir.

Precisa de mais ajuda? Receba respostas de membros da comunidade e profissionais do Google SecOps.