Webhooks voor meldingen

Instellen

Voeg onder Koppelingen een webhook toe met een https-adres van uw systeem. U krijgt één keer een ondertekeningsgeheim (whsec_...) te zien; bewaar het bij uw systeem. Met de knop Testbericht sturen ontvangt u meteen een event van het type endpoint.test.

De webhook ontvangt dezelfde meldingen als uw account, volgens uw meldingsregels, gefilterd op de ernst en de thema's die u bij de webhook kiest.

Het verzoek

Eén POST per melding, met een JSON-body en deze headers:

Content-Type: application/json; charset=utf-8
User-Agent: Checked.be-Webhooks/1.0 (+https://checked.be/nl/developers/webhooks)
webhook-id: Unieke id van het bericht, gelijk aan het veld id. Blijft hetzelfde bij elke herhaling: gebruik het om dubbels te negeren.
webhook-timestamp: Tijdstip van deze poging, in seconden sinds 1970 (UTC).
webhook-signature: De handtekening: v1, gevolgd door de base64-HMAC-SHA256. Zie hieronder.

Voorbeeld

Een melding over een verzonnen bedrijf, precies zoals Checked ze verstuurt:

{
  "id": "msg_5f0c2d6e9b1a4c7d8e3f2a1b0c9d8e7f",
  "type": "alert.created",
  "api_version": "2026-09-25",
  "created_at": "2026-09-25T07:38:12Z",
  "language": "nl",
  "data": {
    "alert": {
      "id": 184223,
      "kind": "bs_capital_change",
      "label": "Kapitaalwijziging",
      "signal": "kapitaal",
      "theme": "financieel",
      "theme_label": "Financieel",
      "severity": "med",
      "severity_label": "midden",
      "title": "Kapitaalverhoging van € 250.000",
      "body": "Het kapitaal stijgt van € 18.550 naar € 268.550.",
      "created_at": "2026-09-25T07:36:12Z"
    },
    "company": {
      "enterprise_number": "0999999999",
      "enterprise_number_display": "0999.999.999",
      "name": "Voorbeeld NV",
      "dossier_url": "https://checked.be/nl/c/voorbeeld-nv-0999999999"
    },
    "alerts_url": "https://checked.be/nl/alerts"
  }
}

Velden

type: alert.created (een melding), digest.created (het dagelijkse of wekelijkse overzicht, als u dat aanvinkt) of endpoint.test (de testknop). Negeer types die u niet kent: er kunnen er bijkomen.
api_version: De versie van dit formaat. Velden kunnen erbij komen; bestaande velden veranderen niet binnen een versie.
language: De taal van de labels en links (nl, fr of en), zoals ingesteld bij de webhook. Titel en tekst van een melding zijn in het Nederlands, zoals in uw account.
data.alert.kind: Het soort melding, een vaste code. label is de naam ervan, signal en theme de rij en het thema uit de meldingsregels (null voor een samenvatting van meerdere akten).
data.alert.severity: low, med of high, met severity_label in de gekozen taal.
data.company: Het ondernemingsnummer (10 cijfers en in de gewone schrijfwijze), de naam (null als die niet bekend is) en de link naar het dossier op Checked.be.

Een webhook krijgt alleen wat de melding in uw account ook toont: geen e-mailadres of andere accountgegevens.

De handtekening controleren

Checked ondertekent volgens Standard Webhooks, zodat u ook een van hun bibliotheken kunt gebruiken. Zelf doen:

Neem de sleutel: het deel na whsec_, base64-gedecodeerd.
Bereken HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{body}, met de body exact zoals ontvangen.
Vergelijk v1, plus de base64 daarvan in constante tijd met elke waarde in webhook-signature (gescheiden door spaties).
Weiger een timestamp die meer dan vijf minuten afwijkt van uw klok.

Node.js

import crypto from "node:crypto";

export function verify(secret, headers, body) {
  const id = headers["webhook-id"];
  const ts = headers["webhook-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = "v1," + crypto.createHmac("sha256", key)
    .update(`${id}.${ts}.${body}`).digest("base64");
  return headers["webhook-signature"].split(" ").some(sig =>
    sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)));
}

Python

import base64, hashlib, hmac, time

def verify(secret: str, headers: dict, body: bytes) -> bool:
    msg_id = headers["webhook-id"]
    ts = headers["webhook-timestamp"]
    if abs(time.time() - int(ts)) > 300:
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{ts}.".encode() + body
    expected = "v1," + base64.b64encode(
        hmac.new(key, signed, hashlib.sha256).digest()).decode()
    return any(hmac.compare_digest(sig, expected)
               for sig in headers["webhook-signature"].split(" "))

using System.Security.Cryptography;
using System.Text;

static bool Verify(string secret, string id, string ts, string signatures, string body)
{
    if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - long.Parse(ts)) > 300) return false;
    var key = Convert.FromBase64String(secret["whsec_".Length..]);
    var hash = HMACSHA256.HashData(key, Encoding.UTF8.GetBytes($"{id}.{ts}.{body}"));
    var expected = Encoding.UTF8.GetBytes("v1," + Convert.ToBase64String(hash));
    return signatures.Split(' ').Any(s =>
        CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(s), expected));
}

Antwoorden en herhalingen

Antwoord binnen 10 seconden met een 2xx-status. Verwerk zwaar werk liever daarna.
Elk ander antwoord, of geen antwoord, wordt herhaald, telkens later: na 1, 5, 15 en 30 minuten, daarna na 1 tot 12 uur. Een bericht wordt tot 6 keer geprobeerd en vervalt na 3 dagen.
Berichten komen in volgorde: zolang het oudste niet aankomt, wachten de volgende. Een Retry-After-header wordt gerespecteerd (tot een uur).
Na 10 mislukte pogingen op rij wordt de webhook uitgeschakeld en krijgt de eigenaar een e-mail. Een antwoord 410 Gone schakelt hem uit zonder nieuwe poging.
Doorverwijzingen (3xx) worden niet gevolgd. Het adres moet https gebruiken en publiek bereikbaar zijn; adressen in een intern netwerk worden geweigerd, ook als de naam later daarheen verwijst.
Elke poging staat in de leverlog bij de webhook, met de status en de duur.