Imagine que toda vez que um vendedor marca uma prospecção como Ganha ou Perdida, você quer disparar uma comemoração no canal do time, atualizar seu CRM ou registrar a venda numa planilha. Você poderia ficar perguntando à API de tempos em tempos "e agora, mudou?" — mas isso é trabalhoso e desperdiça requisições.

Existe um jeito melhor: o webhook. Um webhook é um aviso automático — em vez de você perguntar, o GS Engage é quem te avisa. Você diz "quando acontecer X, me mande um recado nesta URL", e a partir daí cada evento chega sozinho no seu sistema.

Este guia é para quem quer reagir em tempo real ao resultado de uma venda: prospection.won (ganhou) e prospection.lost (perdeu).

sequenceDiagram
  participant V as Vendedor (no app)
  participant GS as GS Engage
  participant U as Sua URL
  V->>GS: Marca a prospecção como Ganha
  GS->>U: POST com o evento prospection.won
  U-->>GS: Responde 200 OK
  Note over GS,U: Se sua URL falhar, o GS reenvia (retries)

Antes de criar o webhook, decida o que você quer ouvir. Para "ganhei ou perdi uma venda", os eventos são:

Existem outros eventos disponíveis, caso você queira acompanhar mais coisas depois:

Agora é hora de registrar o webhook. Você faz isso chamando o endpoint (um endereço da API que executa uma ação) POST /api/v1/webhooks.

Você precisa informar três coisas:

Lembre-se: a autenticação do GS Engage vai na URL, como um parâmetro ?apiKey=SUA_CHAVE. A chave (com cerca de 40 caracteres) é criada na plataforma em Configurações › Configurações de API.

Veja a criação, com curl e com JSON puro:

curl -X POST "https://api.gsengage.com/api/v1/webhooks?apiKey=$GS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Avisos de venda",
    "url": "https://seu-sistema.com.br/webhooks/gsengage",
    "events": ["prospection.won", "prospection.lost"]
  }'

{
  "name": "Avisos de venda",
  "url": "https://seu-sistema.com.br/webhooks/gsengage",
  "events": ["prospection.won", "prospection.lost"]
}

A resposta traz os dados do webhook criado — e, junto, o campo secret:

{
  "id": "6650f1a2b3c4d5e6f7a8b9c0",
  "name": "Avisos de venda",
  "url": "https://seu-sistema.com.br/webhooks/gsengage",
  "events": ["prospection.won", "prospection.lost"],
  "secret": "whsec_9f8e7d6c5b4a3210fedcba9876543210"
}

O secret é o segredo usado para confirmar que o aviso veio mesmo do GS Engage (e não de um impostor). Você vai precisar dele para validar a assinatura de cada entrega.

Quando um evento acontece, o GS Engage faz um POST para a sua URL. O corpo sempre vem no mesmo formato — chamamos isso de envelope:

Exemplo de um evento prospection.won chegando na sua URL:

{
  "id": "del_7a1b2c3d4e5f6a7b8c9d0e1f",
  "test": false,
  "event": "prospection.won",
  "data": {
    "prospection": {
      "id": "6650a1b2c3d4e5f6a7b8c9d0",
      "status": "WON",
      "lead": {
        "id": "6650000011112222aaaabbbb",
        "name": "Marina Souza - Padaria Pão Quente"
      }
    }
  },
  "retries": 0,
  "manualRetries": 0,
  "createdAt": "2026-07-17T14:32:10.000Z"
}

O que isso significa para o negócio: a prospecção com status WON (Ganha) fechou. É o gatilho perfeito para comemorar no time, marcar a venda no seu CRM ou atualizar um painel de metas. Para uma perda, o mesmo envelope chega com "event": "prospection.lost" e o status LOST.

Você não precisa ter um sistema pronto para ver os avisos chegando. Use um coletor de webhooks — uma URL temporária que mostra na tela tudo o que recebe.

Como a sua URL é pública, qualquer um poderia tentar enviar um POST fingindo ser o GS Engage. Para garantir que o aviso é legítimo, cada entrega vem assinada.

A assinatura usa HMAC SHA-256 — uma técnica que combina o corpo da mensagem com o seu secret para gerar um código. Você recalcula esse código do seu lado e compara com o que veio no cabeçalho. Se baterem, o aviso é autêntico.

O passo a passo completo, com código de exemplo, está no guia dedicado:

Depois de criar, você vai querer conferir o que está ativo e, eventualmente, desligar o que não usa mais.

Ver os webhooks que existem

Use GET /api/v1/webhooks. Atenção: essa rota devolve os itens em data, mas sem meta (retorna todos, sem paginação): { "data": [ ... ] }.

curl "https://api.gsengage.com/api/v1/webhooks?apiKey=$GS_API_KEY"

[
  {
    "id": "6650f1a2b3c4d5e6f7a8b9c0",
    "name": "Avisos de venda",
    "url": "https://seu-sistema.com.br/webhooks/gsengage",
    "events": ["prospection.won", "prospection.lost"]
  }
]

O secret não volta aqui — ele só existiu na resposta de criação.

Remover um webhook

Use DELETE /api/v1/webhooks/{webhookId}, colocando o id do webhook. Uma remoção bem-sucedida responde com HTTP 204 (sucesso, sem conteúdo no corpo).

curl -X DELETE "https://api.gsengage.com/api/v1/webhooks/6650f1a2b3c4d5e6f7a8b9c0?apiKey=$GS_API_KEY"

A API tem um rate limit (limite de requisições em um intervalo): janela fixa de 60 segundos, com 200 leituras/min e 100 escritas/min. Ao exceder, você recebe HTTP 429 com o cabeçalho Retry-After (em segundos).

Isso vale para as suas chamadas de gerenciamento dos webhooks (criar, listar, remover) — não para os avisos que você recebe. A boa prática é usar backoff exponencial, respeitando o Retry-After.

Dá para reagir a esses eventos sem programar. O GS Engage expõe gatilhos nativos no Zapier, e ferramentas como Make e n8n também conseguem receber webhooks e consumir a API REST.