Webhooks
All docs
How Ladon delivers alerts to your endpoint, how to check the signature, and how Ladon reacts to your answers. Ladon follows the Standard Webhooks specification, so its libraries work out of the box.
The request
Every message is a POST with a JSON body. The body is described in Events and payloads.
| Header | Value |
|---|---|
Content-Type |
application/json |
User-Agent |
HackIndex-Webhooks/1.0 (+https://ladon.hackindex.io/docs/webhooks) |
webhook-id |
Unique id of this message. Retries of the same message keep the same id |
webhook-timestamp |
Unix time in seconds when the message was signed |
webhook-signature |
One or more signatures, separated by spaces, each starting with v1, |
Checking the signature
Your secret starts with whsec_. To check a message:
- Take the part after
whsec_and base64-decode it. That is the key. - Build the string
{webhook-id}.{webhook-timestamp}.{body}, using the raw body exactly as received. - Compute an HMAC-SHA256 of that string with the key, and base64-encode the result.
- Compare it, in constant time, with each signature in
webhook-signatureafter removingv1,. One match is enough. - Refuse the message when
webhook-timestampis more than 5 minutes away from your clock. That stops replays.
PHP
function ladonSignatureIsValid(string $secret, string $id, string $timestamp, string $body, string $header): bool
{
if (abs(time() - (int) $timestamp) > 300) {
return false;
}
$key = base64_decode(substr($secret, strlen('whsec_')));
$expected = base64_encode(hash_hmac('sha256', "{$id}.{$timestamp}.{$body}", $key, true));
foreach (explode(' ', $header) as $signature) {
if (str_starts_with($signature, 'v1,') && hash_equals($expected, substr($signature, 3))) {
return true;
}
}
return false;
}
Node.js
import { createHmac, timingSafeEqual } from 'node:crypto';
export function ladonSignatureIsValid(secret, id, timestamp, body, header) {
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
return false;
}
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
const expected = createHmac('sha256', key)
.update(`${id}.${timestamp}.${body}`)
.digest();
return header.split(' ').some((signature) => {
if (!signature.startsWith('v1,')) {
return false;
}
const given = Buffer.from(signature.slice(3), 'base64');
return (
given.length === expected.length && timingSafeEqual(given, expected)
);
});
}
Python
import base64, hashlib, hmac, time
def ladon_signature_is_valid(secret: str, id: str, timestamp: str, body: bytes, header: str) -> bool:
if abs(time.time() - int(timestamp)) > 300:
return False
key = base64.b64decode(secret.removeprefix("whsec_"))
message = f"{id}.{timestamp}.".encode() + body
expected = base64.b64encode(hmac.new(key, message, hashlib.sha256).digest()).decode()
return any(
signature.startswith("v1,") and hmac.compare_digest(expected, signature[3:])
for signature in header.split(" ")
)
Go
func LadonSignatureIsValid(secret, id, timestamp string, body []byte, header string) bool {
sent, err := strconv.ParseInt(timestamp, 10, 64)
if err != nil || math.Abs(float64(time.Now().Unix()-sent)) > 300 {
return false
}
key, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_"))
if err != nil {
return false
}
mac := hmac.New(sha256.New, key)
mac.Write([]byte(id + "." + timestamp + "."))
mac.Write(body)
expected := base64.StdEncoding.EncodeToString(mac.Sum(nil))
for _, signature := range strings.Split(header, " ") {
if strings.HasPrefix(signature, "v1,") && hmac.Equal([]byte(expected), []byte(signature[3:])) {
return true
}
}
return false
}
Always check the signature over the raw body. Frameworks that parse and re-encode JSON change the bytes, and the signature no longer matches.
Answering
- Answer with any
2xxstatus within 15 seconds. Do the real work afterwards, for example on a queue. - Use
webhook-idto skip messages you already handled. A retry after a timeout can arrive while you are still processing the first attempt. - Redirects are not followed. Point the channel at the final URL.
- Ladon reads at most 64 KB of your answer and keeps the first 512 bytes in the delivery log.
Retries
When a delivery fails, Ladon tries again after 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours, 14 hours, 20 hours and 24 hours, each with up to 10% random spread. That is about three days in total. A Retry-After header is followed, up to one hour.
| Error in the delivery log | Meaning |
|---|---|
non_2xx |
Your endpoint answered with another status than 2xx |
redirect |
Your endpoint answered with a redirect |
timeout |
No complete answer within 15 seconds, or no connection within 5 |
connect |
The connection was refused or dropped |
tls |
The certificate is invalid, expired or for another host |
dns |
The host name does not resolve |
ssrf_blocked |
The host name points to a private or reserved address. Ladon does not send there |
invalid_url |
The URL itself is not allowed, for example not https |
ssrf_blocked and invalid_url are not retried, because only a new URL helps. A 410 Gone switches the channel off right away. What else happens when deliveries keep failing is in Channels.
Verifying your endpoint
When you add a webhook channel or change its URL, Ladon sends a message of type endpoint.verify with a random data.challenge. Answer within 10 seconds with a 2xx status and this JSON body:
{ "challenge": "the value of data.challenge" }
Until then the channel waits for verification and receives no alerts. You can retry the check from the channel page.
Rotating the secret
Rotate the secret on the channel page when it may have leaked, or as a routine. The new secret is shown once. For 24 hours Ladon signs with both the old and the new secret, so webhook-signature contains two signatures. Deploy the new secret within that time.
Network
Ladon only connects from its own servers. The outgoing IP addresses will be published here, so you can allow them in your firewall. Do not rely on them alone: always check the signature.