# Webhooks

Hoe Ladon meldingen bij je endpoint aflevert, hoe je de handtekening controleert, en hoe Ladon op je antwoorden reageert. Ladon volgt de [Standard Webhooks](https://www.standardwebhooks.com/)-specificatie, dus de bibliotheken daarvan werken meteen.

## Het request

Elk bericht is een `POST` met een JSON-body. De body staat beschreven in [Events en payloads](https://ladon.hackindex.io/nl/docs/events.md).

| Header              | Waarde                                                                              |
| ------------------- | ----------------------------------------------------------------------------------- |
| `Content-Type`      | `application/json`                                                                  |
| `User-Agent`        | `HackIndex-Webhooks/1.0 (+https://ladon.hackindex.io/docs/webhooks)`                                                              |
| `webhook-id`        | Unieke id van dit bericht. Nieuwe pogingen van hetzelfde bericht houden dezelfde id |
| `webhook-timestamp` | Unix-tijd in seconden waarop het bericht is ondertekend                             |
| `webhook-signature` | Een of meer handtekeningen, gescheiden door spaties, elk beginnend met `v1,`        |

## De handtekening controleren

Je secret begint met `whsec_`. Zo controleer je een bericht:

1. Neem het deel na `whsec_` en decodeer het met base64. Dat is de sleutel.
2. Maak de string `{webhook-id}.{webhook-timestamp}.{body}`, met de ruwe body precies zoals ontvangen.
3. Bereken een HMAC-SHA256 van die string met de sleutel en codeer het resultaat met base64.
4. Vergelijk dat in constante tijd met elke handtekening in `webhook-signature`, zonder `v1,`. Eén overeenkomst is genoeg.
5. Weiger het bericht als `webhook-timestamp` meer dan 5 minuten van je eigen klok afwijkt. Zo voorkom je dat oude berichten opnieuw worden afgespeeld.

### PHP

```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

```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

```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

```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
}
```

Controleer de handtekening altijd over de ruwe body. Frameworks die JSON inlezen en opnieuw coderen, veranderen de bytes, en dan klopt de handtekening niet meer.

## Antwoorden

- Antwoord binnen 15 seconden met een `2xx`-status. Doe het echte werk daarna, bijvoorbeeld via een queue.
- Gebruik `webhook-id` om berichten over te slaan die je al hebt verwerkt. Een nieuwe poging na een timeout kan binnenkomen terwijl je de eerste nog verwerkt.
- Redirects volgen we niet. Laat het kanaal naar de uiteindelijke URL wijzen.
- Ladon leest maximaal 64 KB van je antwoord en bewaart de eerste 512 bytes in het bezorglog.

## Nieuwe pogingen

Mislukt een bezorging, dan probeert Ladon het opnieuw na 5 seconden, 5 minuten, 30 minuten, 2 uur, 5 uur, 10 uur, 14 uur, 20 uur en 24 uur, elk met tot 10% willekeurige spreiding. Dat is samen ongeveer drie dagen. Een `Retry-After`-header volgen we, tot maximaal een uur.

| Fout in het bezorglog | Betekenis                                                                               |
| --------------------- | --------------------------------------------------------------------------------------- |
| `non_2xx`             | Je endpoint antwoordde met een andere status dan `2xx`                                  |
| `redirect`            | Je endpoint antwoordde met een redirect                                                 |
| `timeout`             | Geen volledig antwoord binnen 15 seconden, of geen verbinding binnen 5                  |
| `connect`             | De verbinding werd geweigerd of verbroken                                               |
| `tls`                 | Het certificaat is ongeldig, verlopen of voor een andere host                           |
| `dns`                 | De hostnaam bestaat niet                                                                |
| `ssrf_blocked`        | De hostnaam wijst naar een privé- of gereserveerd adres. Daar stuurt Ladon niet naartoe |
| `invalid_url`         | De URL zelf is niet toegestaan, bijvoorbeeld geen `https`                               |

Bij `ssrf_blocked` en `invalid_url` proberen we het niet opnieuw, omdat alleen een nieuwe URL helpt. Een `410 Gone` zet het kanaal meteen uit. Wat er verder gebeurt als bezorgen blijft mislukken, staat in [Kanalen](https://ladon.hackindex.io/nl/docs/channels.md).

## Je endpoint verifiëren

Voeg je een webhook-kanaal toe of wijzig je de URL, dan stuurt Ladon een bericht van type `endpoint.verify` met een willekeurige `data.challenge`. Antwoord binnen 10 seconden met een `2xx`-status en deze JSON-body:

```json
{ "challenge": "de waarde van data.challenge" }
```

Tot die tijd wacht het kanaal op verificatie en krijgt het geen meldingen. Je kunt de controle opnieuw starten vanaf de kanaalpagina.

## Het secret vernieuwen

Vernieuw het secret op de kanaalpagina als het misschien is uitgelekt, of gewoon regelmatig. Het nieuwe secret wordt één keer getoond. Ladon ondertekent 24 uur lang met het oude en het nieuwe secret, dus `webhook-signature` bevat dan twee handtekeningen. Zet het nieuwe secret binnen die tijd in je eigen systeem.

## Netwerk

Ladon maakt alleen verbinding vanaf zijn eigen servers. De uitgaande IP-adressen publiceren we hier, zodat je ze in je firewall kunt toestaan. Vertrouw daar niet alleen op: controleer altijd de handtekening.
