Webhooks
Envie eventos para Discord, Slack, n8n ou seus próprios sistemas
Os webhooks empurram eventos da Predite para o seu próprio servidor no instante em que eles acontecem — sem polling. Quando um bot preenche uma operação, um stop-loss dispara ou o scanner encontra um novo edge, a Predite envia um HTTP POST para uma URL que você controla. Os webhooks são um recurso do plano Bot e são gerenciados em Configurações, na página Webhooks.
Criando um webhook
Você precisa de três coisas: uma URL que aceite requisições POST, um rótulo para diferenciar os seus webhooks e pelo menos um evento assinado.
A sua URL precisa ser https em produção. A Predite se recusa a entregar em endereços privados, de loopback ou de rede interna, e não segue redirects — isso protege a sua conta de um endpoint mal configurado ser usado para alcançar o interior da nossa infraestrutura.
Eventos
Existem seis eventos. Quatro estão ativos hoje:
- •ev_signal — o scanner publicou um novo sinal de Expected Value. Enviado a todos os assinantes (não é específico do usuário).
- •arb_opportunity — uma nova oportunidade de arbitragem entre plataformas foi encontrada. Também enviado a todos os assinantes.
- •bot_trade_executed — um dos seus bots abriu uma posição, ao vivo ou em paper.
- •stop_loss_triggered — uma das suas saídas de proteção (stop-loss, take-profit ou trailing stop) fechou uma posição.
Outros dois estão reservados e aparecem marcados como em breve no dashboard — whale_move e resolution_imminent. Você já pode assiná-los hoje, mas eles ainda não entregam nada.
Eventos sobre a sua própria atividade são enviados apenas para você. Eventos de alcance geral, do mercado inteiro, vão para todos que os assinaram.
Formato do payload
Toda entrega é um POST com um corpo JSON neste formato:
- •event — o nome do evento, por exemplo bot_trade_executed
- •timestamp — quando o evento aconteceu, em ISO-8601
- •data — um objeto com os detalhes daquele evento
Junto dele, a Predite envia estes cabeçalhos:
- •X-Predite-Event — o nome do evento
- •X-Predite-Timestamp — o mesmo timestamp
- •X-Predite-Signature — a assinatura, formatada como sha256=<hex>
Verificando a assinatura
Cada webhook tem o seu próprio segredo, exibido no dashboard e começando com whsec_. A assinatura é um HMAC-SHA256 do corpo bruto da requisição, com chave nesse segredo, codificado em hexadecimal e prefixado com sha256=.
Para verificar, calcule o HMAC do corpo que você recebeu e compare com o cabeçalho X-Predite-Signature. Se não baterem, rejeite a requisição — ela não veio de nós. Sempre verifique antes de agir sobre um payload, e sempre use o corpo bruto, não uma versão re-serializada do JSON já parseado.
Entrega, falhas e desativação automática
- •Cada evento é entregue em uma única tentativa, com timeout de 5 segundos. Não há retentativas automáticas — projete o seu endpoint para responder rápido e fazer o trabalho lento depois.
- •Qualquer resposta não-2xx, timeout ou erro de conexão conta como falha.
- •Depois de 10 falhas consecutivas, o webhook é automaticamente desativado e aparece como AUTO-DISABLED. Um único sucesso zera o contador.
- •Reativar pelo dashboard um webhook desativado limpa a contagem de falhas.
Toda tentativa é registrada, então o dashboard mostra o total de entregas, as falhas consecutivas, o último sucesso, a última falha e o motivo da falha.
Vale saber
- •Responda 2xx assim que tiver armazenado o evento; qualquer coisa mais lenta arrisca o timeout de 5 segundos.
- •Como não há retentativas, trate os webhooks como um canal rápido de notificação e não como um livro-razão garantido — reconcilie contra a API Pública se você precisar de certeza.
- •Você pode pausar um webhook a qualquer momento, em vez de excluí-lo.