Webhooks ontvangen & controleren

Een webhook meldt wat er veranderde

Een webhook is een HTTPS POST van MANE naar een adres dat jij beheert. De melding bevat metadata zoals gebeurtenis-ID, type, dossier-ID en revisie. De dossierinhoud haal je daarna op met een eigen servicesleutel en passend leesrecht.

Wijzigingen uit MANE en uit de API kunnen een melding opleveren. Eén handeling kan meerdere gebeurtenissen geven, bijvoorbeeld projects.updated én tasks.created. De bezorging is asynchroon: je moet rekening houden met vertraging, dubbele bezorging en een andere aankomstvolgorde.

Een webhook instellen

Open Instellingen → API & webhooks → Webhook toevoegen. Vul naam en het publieke HTTPS-ontvangstadres in. Kies de onderdelen met de selectievakjes. Bewaar de ondertekeningssleutel, controleer je ontvanger en schakel de webhook bewust in.

Het adres gebruikt HTTPS op poort 443, zonder gebruikersnaam, wachtwoord of fragment. Lokale/private adressen, IP-literals en doorverwijzingen worden niet gebruikt. Een webhook staat bij aanmaken standaard uit tenzij enabled:true is meegegeven.

Een voorbeeldmelding

Onderstaande waarden zijn fictief. Bewaar id als string. Voor een taak gebruik je data.projectId plus data.recordId om het detail op te halen. Bij een deleted-event is dat dossier mogelijk al niet meer op te halen.

companyId staat in het data-object van een bezorgde webhook. De events-ophaalroute geeft een lijst van metadata binnen de al geauthenticeerde werkruimte. sourceKeyId is null bij wijzigingen zonder API-sleutel.

{
  "specversion":"1.0",
  "id":"1042",
  "type":"tasks.created",
  "source":"mane",
  "data":{
    "id":"1042",
    "type":"tasks.created",
    "companyId":"co_…",
    "resource":"tasks",
    "recordId":"api_…",
    "projectId":"project-…",
    "revision":42,
    "sourceKeyId":null,
    "occurredAt":"2026-10-19T08:00:00Z"
  }
}

Controleer de afzender vóór verwerking

Gebruik de oorspronkelijke requestbody, exact zoals ontvangen. Maak er voor de controle geen opnieuw geserialiseerd JSON-object van. MANE stuurt X-MANE-Timestamp, X-MANE-Signature, X-MANE-Event-Id en X-MANE-Delivery-Id.

De verwachte signature is v1= plus de hex-uitvoer van HMAC-SHA256 met je mwh_-ondertekeningssleutel over timestamp + "." + de ongewijzigde body. Vergelijk met een constante-tijdvergelijking en accepteer alleen timestamps binnen vijf minuten. Bescherm je ontvanger daarnaast tegen herhaalde event-ID’s.

Kan je Make- of n8n-configuratie geen exacte raw body of veilige HMAC-controle bieden, plaats er dan een eigen verificatie-endpoint voor. Een geheim ontvangst-URL alleen is geen controle van de MANE-handtekening.

import {createHmac, timingSafeEqual} from "node:crypto";
function valid(secret, timestamp, rawBody, signature) {
  if (!/^\d{10}$/.test(timestamp) ||
      Math.abs(Date.now()/1000 - Number(timestamp)) > 300 ||
      !/^v1=[a-f0-9]{64}$/.test(signature || "")) return false;
  const expected = "v1=" + createHmac("sha256", secret)
    .update(timestamp + ".").update(rawBody).digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Ontvangen, bewaren en antwoorden

Controleer de signature, leg het event duurzaam vast met een unieke sleutel voor webhook plus event-ID en antwoord snel met 2xx. Verwerk het werk daarna uit je eigen wachtrij. Als duurzaam bewaren mislukt, geef geen succes terug.

Ontvang je dezelfde gebeurtenis opnieuw en was hij al opgeslagen, geef dan opnieuw 2xx zonder de zakelijke actie nogmaals uit te voeren. De inhoud kan inmiddels veranderd zijn: gebruik de revisie als je de gebeurtenisversie nodig hebt, of lees bewust de nieuwste versie.

Fouten, pauzeren en opnieuw proberen

Een ontvanger heeft maximaal acht seconden voor een antwoord. MANE probeert een mislukte bezorging maximaal zes keer met oplopende wachttijd. Daarna zie je aandacht nodig bij de webhook. Opnieuw proberen zet mislukte bezorgingen weer klaar; het vervangt je eigen ontdubbeling niet.

Pauzeren stopt nieuwe bezorgingen en annuleert wachtende pogingen. Een netwerkverzoek dat al onderweg is kan nog aankomen. Opnieuw inschakelen haalt gepauzeerde meldingen niet automatisch in. Gebruik GET /events?after=<laatste-id> voor herstel en controleer wat je workflow al heeft verwerkt.

Pas een bestemming of de gebeurteniskeuze aan door een nieuwe webhook te maken en de oude te verwijderen. De API ondersteunt bij PATCH alleen enabled en retryFailed; geen stille sleutelrotatie of URL-wijziging.