Webhooks: receba um POST a cada gol

O gol não avisa que vem

Todo o resto do futebol tem aviso prévio. A escalação sai uma hora antes. O escanteio dá tempo de posicionar. Até o pênalti tem a caminhada até a marca.

O gol, não. Ele é o único evento do esporte que acontece inteiro em menos de um segundo, e que reorganiza tudo ao redor no instante seguinte: a tabela muda, a artilharia muda, o mercado de apostas muda, a narrativa da rodada muda. Não existe transição — existe antes e depois.

É por isso que futebol é um dos poucos assuntos em que atraso de dez segundos é percebido como defeito pelo usuário final. Quando o app avisa depois do grito do vizinho, o app perdeu. O torcedor não pensa “o servidor demorou”. Ele pensa que o produto está quebrado.

Onde o polling deixa de servir

Fazer polling a cada 15 segundos funciona bem para exibir placar — a tela precisa estar certa, não instantânea.

Mas alguns casos de uso não toleram a janela. Um bot que posta o gol no grupo. Uma notificação push. Um alerta que dispara quando o time do usuário marca. Um painel de operação que precisa reagir. Nesses casos você não quer perguntar “teve gol?” mil vezes por dia — você quer ser avisado uma vez, no momento certo.

É a diferença entre ficar atualizando a página e receber a ligação.

Registre seu webhook

curl -X POST https://api.dadosfutebol.com.br/v1/webhooks \
  -H "Authorization: Bearer SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meuapp.com.br/webhooks/futebol",
    "eventos": ["partida.gol"]
  }'

O evento partida.gol é emitido durante o jogo, assim que o monitor de tempo real detecta a mudança no placar — com autor do gol, minuto e tipo (gol normal, contra ou pênalti). Ou seja: chega com a informação que a notificação precisa, não só “o placar mudou”.

Confie, mas verifique

Cada webhook tem um segredo usado para assinar as entregas — valide a assinatura antes de processar o payload. Se o segredo vazar, rotacione sem recriar o webhook:

curl -X POST https://api.dadosfutebol.com.br/v1/webhooks/{id}/rotacionar-segredo \
  -H "Authorization: Bearer SUA_CHAVE_AQUI"

Teste e acompanhe as entregas

Antes de esperar um gol de verdade, dispare uma entrega de teste e depois inspecione o histórico — cada tentativa fica registrada com status e resposta do seu servidor:

# entrega de teste
curl -X POST https://api.dadosfutebol.com.br/v1/webhooks/{id}/testar \
  -H "Authorization: Bearer SUA_CHAVE_AQUI"

# histórico de entregas
curl https://api.dadosfutebol.com.br/v1/webhooks/{id}/entregas \
  -H "Authorization: Bearer SUA_CHAVE_AQUI"

Se o seu endpoint ficar fora do ar, as entregas com falha aparecem nesse histórico — é o primeiro lugar para investigar quando “o webhook não chegou”. Vale testar antes da rodada de domingo, não durante.

CRUD completo

Webhooks são recursos normais da API: GET /v1/webhooks lista, PATCH /v1/webhooks/{id} atualiza a URL ou os eventos, DELETE /v1/webhooks/{id} remove. Tudo escopado à sua conta.

No próximo post da série: como consumir esses mesmos dados direto num assistente de IA, via servidor MCP.