Webhooks

How to have Okkana send each Signal to your own server or automation: registering the URL, what arrives, how to check it came from Okkana and what happens when your server is down.

A webhook is an address on your side that Okkana calls when something happens. When a bot with the webhook channel turned on fires, Okkana sends an HTTPS POST with the Signal as JSON to that address, a few moments later. Take profit and stop loss hits on your open operations are sent the same way.

It's how a Signal gets out of Okkana and into something else: an n8n or Make flow, a script that logs it to a spreadsheet, a program of your own. Okkana only sends the message. What happens next is up to the receiver, and Okkana never places an order.

The body is Okkana's own JSON. Chat apps like Discord and Telegram expect a different format, so between Okkana and them you need a receiver that translates, such as an automation tool or a few lines of code.

In your profile, add a webhook with a public https:// address. The API rejects an address that isn't https, that has a user and password in it, or that points at a local name or a private network address: localhost, .local, 192.168.x.x. Try some in the field.

When it's saved, Okkana shows the signing secret, a value starting with whsec_. It appears once, so copy it then. You use it to check that each request really came from Okkana.

The URL alone sends nothing. Each bot has a webhook channel you turn on, and only those bots deliver to it. You can also set an authentication header, such as an Authorization with a token of yours, which Okkana sends with every request, and send a test request from the profile to see your server answer.

Every request is a POST with a JSON body and a few headers. Okkana-Event says which kind it is: signal.triggered when a bot fires, signal.exit when an open operation hits the bot's take profit or stop loss, and webhook.test for the test request.

A Signal delivery carries the whole Signal: market, direction, entry price, the rule that fired with each condition's values, and the performance windows. Okkana-Signal-Id is the Signal's id and stays the same on every retry. An exit delivery has Okkana-Exit-Id instead.

Okkana-Delivery-Id identifies one delivery.

Anyone who finds your URL can post to it. The Okkana-Signature header lets you tell Okkana's requests from the rest. It has two parts: t, the Unix time of the send, and v1, an HMAC-SHA256 in hex.

To check it, compute the HMAC-SHA256 of the text t, a dot and the raw body, using your signing secret as the key, and compare it with v1. Use the body exactly as it arrived, before parsing the JSON: a different space or line break gives a different result. Compare in constant time, and reject a t that's too far from the current time, five minutes for example, so an old request can't be replayed.

Changing a single character of the body changes the whole signature.

Answer with a 2xx status quickly: the sender waits 5 seconds, doesn't follow redirects and ignores the response body. A 2xx marks the delivery as done.

A timeout, a connection or TLS error, a 408, a 429 or a 5xx is retried: up to 9 attempts over about 22 hours, waiting 30 s, 1 min, 5 min, 15 min, 1 h, 3 h, 6 h and 12 h between them, each wait varied by about 20%. If you send Retry-After, the longer wait wins, up to 6 hours. Other answers, such as a 404 or a redirect, end the delivery with no retry.

Because of the retries, the same Signal can reach you more than once. Use Okkana-Signal-Id (or Okkana-Exit-Id for an exit) to drop repeats.

If the secret leaks, generate a new one: the URL stays the same, the new secret is shown once, and the old one stops being valid. Saving a different URL replaces the webhook and also issues a new secret. Revoking stops deliveries to the address, including retries that were still waiting, and your bots keep the webhook channel turned on.

A test request goes out from your profile and isn't added to the webhook's delivery record. It's limited to 3 a minute and 20 an hour, one at a time.

Keep the secret on the server that receives the requests, never in a page or an app that other people can open. An authentication header you configure has reserved names: Content-Type, Host, User-Agent and anything starting with Okkana- or Proxy- is rejected.