​

Webhooks

​

Catálogo de eventos

​

partida.gol

{
  "evento": "partida.gol",
  "gerado_em": "2026-07-25T21:52:09-03:00",
  "dados": {
    "id": 2903,
    "placar_mandante": 1,
    "placar_visitante": 1,
    "gol": {
      "tipo": "gol",
      "jogador": "Vegetti",
      "time_nome": "Vasco",
      "minuto": 80
    },
    "gols": [
      { "tipo": "gol", "jogador": "Pedro", "time_nome": "Flamengo", "minuto": 22 },
      { "tipo": "gol", "jogador": "Vegetti", "time_nome": "Vasco", "minuto": 80 }
    ]
  }
}

​

Formato do payload

{
  "evento": "partida.encerrada",
  "gerado_em": "2026-05-27T20:15:00-03:00",
  "dados": {
    "id": 1234,
    "campeonato_id": 4,
    "rodada_numero": 12,
    "fase": null,
    "status": "encerrado",
    "placar_mandante": 2,
    "placar_visitante": 1,
    "time_mandante": { "id": 1, "nome": "Flamengo", "sigla": "FLA" },
    "time_visitante": { "id": 2, "nome": "Palmeiras", "sigla": "PAL" },
    "estadio": "Maracanã",
    "gols": [
      { "tipo": "gol", "jogador": "Pedro", "time_nome": "Flamengo", "minuto": 22 },
      { "tipo": "penalti", "jogador": "Arrascaeta", "time_nome": "Flamengo", "minuto": 61 },
      { "tipo": "gol", "jogador": "Estêvão", "time_nome": "Palmeiras", "minuto": 78 }
    ]
  }
}

​

gols

​

Headers da requisição

​

Verificação da assinatura

import crypto from "crypto";

// req.body deve ser o corpo BRUTO (ex.: express.raw)
function verificar(req, secret) {
  const assinatura = req.header("X-DF-Assinatura");
  const timestamp = req.header("X-DF-Timestamp");
  const corpo = req.body.toString("utf8");

  const esperado = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${corpo}`)
    .digest("hex");

  return crypto.timingSafeEqual(Buffer.from(assinatura), Buffer.from(esperado));
}

function verificar(string $corpo, array $headers, string $secret): bool
{
    $assinatura = $headers['X-DF-Assinatura'] ?? '';
    $timestamp  = $headers['X-DF-Timestamp'] ?? '';

    $esperado = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $corpo, $secret);

    return hash_equals($esperado, $assinatura);
}

import hmac, hashlib

def verificar(corpo: bytes, headers: dict, secret: str) -> bool:
    assinatura = headers.get("X-DF-Assinatura", "")
    timestamp = headers.get("X-DF-Timestamp", "")
    esperado = "sha256=" + hmac.new(
        secret.encode(), f"{timestamp}.".encode() + corpo, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(esperado, assinatura)

​

Entrega e retentativas

• O seu endpoint deve responder com status 2xx. Qualquer outro status (ou timeout) é tratado como falha. Redirecionamentos (3xx) não são seguidos.
• Falhas temporárias (5xx, timeout, falha de conexão, 408, 429) são reenviadas com backoff crescente (segundos → minutos → 1 hora) por algumas tentativas.
• Falhas permanentes (3xx e demais 4xx — endereço errado, rota inexistente, método não aceito) não são retentadas: a entrega é marcada como falha na primeira resposta.
• Após muitas falhas consecutivas o webhook é desativado automaticamente e religado no dia seguinte para uma nova chance.
• Se as falhas se acumularem sem nenhuma entrega bem-sucedida no meio, a desativação vira definitiva: você recebe um e-mail avisando, e o webhook só volta quando você corrigir o endpoint e reativá-lo no painel ou via PATCH /v1/webhooks/{id} ("ativo": true). Atualizar a URL também zera o histórico de falhas.
• Cada entrega traz um X-DF-Entrega único — armazene-o e ignore duplicatas (a entrega é at-least-once; a ordem não é garantida).
• A URL precisa usar HTTPS e apontar para um host público.

​

Cota de entregas

• Conta apenas entregas com resposta 2xx — retentativas por falha do seu endpoint não consomem a cota.
• É compartilhada entre todos os seus webhooks (somada por conta) e reseta no dia 1º de cada mês (UTC).
• Eventos de gerenciamento via API (criar, listar, testar etc.) usam a cota de requisições normal, não a de entregas.

{
  "meta": {
    "entregas_mes_usadas": 1240,
    "entregas_mes_limite": 20000,
    "entregas_referencia": "202605"
  }
}

​

Gerenciamento via API

​

Criar um webhook

curl -X POST https://api.dadosfutebol.com.br/v1/webhooks \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Produção",
    "url": "https://seu-dominio.com/webhook",
    "eventos": ["partida.ao_vivo", "partida.placar_atualizado", "partida.encerrada"]
  }'

{
  "data": {
    "id": 10,
    "nome": "Produção",
    "url": "https://seu-dominio.com/webhook",
    "eventos": ["partida.ao_vivo", "partida.placar_atualizado", "partida.encerrada"],
    "ativo": true,
    "secret": "a1b2c3...«guarde com segurança»"
  },
  "mensagem": "Guarde o secret com segurança — ele não será exibido novamente."
}

​

Cotas por plano

{
  "erro": "Limite do plano",
  "mensagem": "Seu plano permite no máximo 1 webhook(s) ativo(s). Faça upgrade ou desative um existente."
}