Webhooks

Como fazer o Okkana enviar cada sinal para o seu servidor ou automação: cadastrar a URL, o que chega, como conferir que veio do Okkana e o que acontece quando o seu servidor está fora do ar.

Um webhook é um endereço seu que o Okkana chama quando algo acontece. Quando um bot com o canal webhook ligado dispara, o Okkana envia ao seu endereço um POST HTTPS com o sinal em JSON, poucos instantes depois. Os toques no take profit e no stop loss das suas operações abertas seguem o mesmo caminho.

É assim que um sinal sai do Okkana e entra em outra coisa: um fluxo do n8n ou do Make, um script que grava numa planilha, um programa seu. O Okkana só envia a mensagem. O que acontece depois é com quem recebe, e o Okkana nunca envia ordens.

O corpo é o JSON do próprio Okkana. Apps de chat como Discord e Telegram esperam outro formato, então entre o Okkana e eles é preciso um receptor que traduza, como uma ferramenta de automação ou algumas linhas de código.

No seu perfil, adicione um webhook com um endereço https:// público. A API recusa endereço sem https, com usuário e senha, ou que aponte para nome local ou rede privada: localhost, .local, 192.168.x.x. Teste alguns no campo.

Ao salvar, o Okkana mostra o segredo de assinatura, um valor que começa com whsec_. Ele aparece uma única vez, então copie na hora. É com ele que você confere que cada requisição veio mesmo do Okkana.

A URL sozinha não envia nada. Cada bot tem um canal webhook que você liga, e só esses bots entregam nela. Também dá para configurar um header de autenticação, como um Authorization com um token seu, que o Okkana manda em toda requisição, e enviar uma requisição de teste pelo perfil para ver o seu servidor responder.

Toda requisição é um POST com corpo JSON e alguns headers. O Okkana-Event diz o tipo: signal.triggered quando um bot dispara, signal.exit quando uma operação aberta toca o take profit ou o stop loss do bot, e webhook.test para a requisição de teste.

A entrega de um sinal leva o sinal inteiro: mercado, direção, preço de entrada, a regra que disparou com os valores de cada condição e as janelas de desempenho. O Okkana-Signal-Id é o id do sinal e se mantém igual em cada nova tentativa. A entrega de saída traz o Okkana-Exit-Id no lugar.

O Okkana-Delivery-Id identifica uma entrega.

Quem descobrir a sua URL consegue enviar requisições para ela. O header Okkana-Signature permite separar as do Okkana das demais. Ele tem duas partes: t, o horário Unix do envio, e v1, um HMAC-SHA256 em hexadecimal.

Para conferir, calcule o HMAC-SHA256 do texto t, um ponto e o corpo bruto, usando o seu segredo de assinatura como chave, e compare com o v1. Use o corpo exatamente como chegou, antes de interpretar o JSON: um espaço ou quebra de linha diferente muda o resultado. Compare em tempo constante e recuse um t muito distante da hora atual, cinco minutos por exemplo, para que uma requisição antiga não seja reenviada por outra pessoa.

Trocar um único caractere do corpo muda a assinatura inteira.

Responda com um status 2xx rápido: o envio espera 5 segundos, não segue redirecionamentos e ignora o corpo da resposta. Um 2xx marca a entrega como concluída.

Timeout, erro de conexão ou de TLS, um 408, um 429 ou um 5xx geram nova tentativa: até 9 tentativas em cerca de 22 horas, com espera de 30 s, 1 min, 5 min, 15 min, 1 h, 3 h, 6 h e 12 h entre elas, cada espera variando cerca de 20%. Se você enviar Retry-After, vale a espera maior, até 6 horas. Outras respostas, como um 404 ou um redirecionamento, encerram a entrega sem nova tentativa.

Por causa das novas tentativas, o mesmo sinal pode chegar mais de uma vez. Use o Okkana-Signal-Id (ou o Okkana-Exit-Id, numa saída) para descartar repetidos.

Se o segredo vazar, gere um novo: a URL continua a mesma, o novo segredo aparece uma única vez e o antigo deixa de valer. Salvar outra URL substitui o webhook e também emite um novo segredo. Revogar interrompe as entregas para o endereço, inclusive as novas tentativas que ainda esperavam, e os seus bots continuam com o canal webhook ligado.

A requisição de teste sai do seu perfil e não entra no histórico de entregas do webhook. O limite é de 3 por minuto e 20 por hora, uma de cada vez.

Guarde o segredo no servidor que recebe as requisições, nunca numa página ou app que outras pessoas possam abrir. O header de autenticação que você configura tem nomes reservados: Content-Type, Host, User-Agent e tudo que comece com Okkana- ou Proxy- é recusado.