Documentatie

Een zoekopdracht maken

Een zoekopdracht bestaat uit drie dingen: een gebied, een soort werk en een fase.

• Gebied. Een postcode of adres met een straal in kilometers, een gemeente of een provincie. In het dashboard teken je het werkgebied op de kaart.
• Soort werk. Bijvoorbeeld dakkapel, uitbouw, sloop, kappen of zonnepanelen. Een bericht kan onder meer dan één soort vallen. Laat je dit leeg, dan krijg je alles in je gebied.
• Fase. Aanvraag, ontwerpbesluit, verleend. Standaard staan deze drie aan. Je kunt ze afzonderlijk uitzetten.

Je geeft de zoekopdracht een naam, zoals "Dakkapellen binnen 15 km". Die naam staat in elke mail. Het aantal zoekopdrachten hangt af van je plan: 1 bij Gratis, 10 bij Pro, 50 bij Team.

Soorten meldingen

• Directe mail. Eén mail per melding, kort na het inlezen van de bekendmakingen (op werkdagen na 10:15, en na een tweede ronde om 13:00). Voor Pro en Team.
• Dagoverzicht. Eén mail om 07:00. Voor alle plannen.
• Weekoverzicht. Voor het gratis plan. Meldingen komen 7 dagen later dan bij Pro en Team.
• Webhook. Een POST naar je eigen adres per melding. Voor Team.

Je zoekopdrachten stel je per stuk in op direct of dagoverzicht. Een melding bevat het adres, het werk, de fase, de datum, het zaaknummer en een link naar de officiële bekendmaking. Bij een besluit staat de datum waarop de bezwaartermijn eindigt. Zie de voorbeelden.

Dagoverzicht

Het dagoverzicht verschijnt om 07:00 en toont de meldingen van de vorige werkdag voor al je zoekopdrachten, in één mail. Het onderwerp is "4 nieuwe meldingen, woensdag 7 oktober 2026". Afmelden kan met één klik onderaan de mail.

Webhook

Met Team stuurt Vergunningwacht elke nieuwe melding als JSON naar een adres dat jij opgeeft. Je koppelt het aan je CRM, planning of een eigen script.

• Het adres moet https zijn en publiek bereikbaar. Adressen als localhost of interne IP-adressen worden geweigerd. Redirects volgen we niet.
• Wij sturen een POST met content-type: application/json. Antwoord binnen 10 seconden met een 2xx-status.
• Lukt het niet, dan proberen we het opnieuw na 1, 5, 30 en 120 minuten, met in totaal vijf pogingen. Een melding die ouder is dan drie dagen sturen we niet meer.
• Mislukt het 10 keer achter elkaar (10 rondes zonder één geslaagde bezorging), dan zetten we de webhook uit. Je kunt hem weer aanzetten in het dashboard.
• Het veld delivery is uniek per bezorging. Gebruik het om dubbele verwerking te voorkomen.

Voorbeeld van de inhoud

{
  "event": "notice.matched",
  "delivery": "voorbeeld-delivery-id",
  "watch": { "id": "voorbeeld-watch-id", "name": "Dakkapellen binnen 15 km" },
  "notice": {
    "id": "gmb-2026-000000",
    "municipality_code": "GM9999",
    "creator": "Voorbeeldstad",
    "published_at": "2026-10-06",
    "rubriek": "omgevingsvergunning",
    "stage": "verleend",
    "title": "Voorbeeldstad, Heideweg 48: verleende omgevingsvergunning, plaatsen dakkapel",
    "abstract": null,
    "url": "https://zoek.officielebekendmakingen.nl/gmb-2026-000000.html",
    "lat": 52.1, "lon": 5.1,
    "postcode": "1234 AB", "street": "Heideweg", "house_number": "48", "place": "Voorbeeldstad",
    "zaaknummer": "VOORB-2026-0388",
    "objection_until": "2026-11-17",
    "applicant_org": null,
    "activities": ["dakkapel"]
  }
}

Velden die ontbreken in de bekendmaking zijn null. We sturen nooit de naam van een persoon mee. applicant_org is alleen gevuld als de aanvrager een bedrijf is.

Handtekening controleren

Elk verzoek heeft de header x-vergunningwacht-signature, in de vorm t=1791281000,v1=9b2f.... De waarde t is de tijd in seconden (Unix). De waarde v1 is een HMAC met SHA-256 over de tekst t + "." + inhoud, met jouw webhook-geheim als sleutel, in hexadecimaal.

Controleer drie dingen: dat t niet te oud is (bijvoorbeeld meer dan vijf minuten), dat de handtekening klopt, en gebruik hiervoor de ruwe tekst van het verzoek. Een geparst en opnieuw geschreven JSON-object geeft een andere handtekening.

JavaScript (Node)

import crypto from "node:crypto";

// rawBody: de ongewijzigde tekst van het verzoek, niet het geparste JSON-object.
export function verify(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express: app.post("/hook", express.raw({ type: "application/json" }), (req, res) => {
//   if (!verify(req.body.toString("utf8"), req.get("x-vergunningwacht-signature") ?? "", process.env.VW_SECRET)) return res.sendStatus(401);
//   res.sendStatus(200);
// });

PHP

<?php
function vw_verify(string $rawBody, string $header, string $secret, int $tolerance = 300): bool {
    $parts = [];
    foreach (explode(',', $header) as $p) {
        [$k, $v] = array_pad(explode('=', $p, 2), 2, '');
        $parts[$k] = $v;
    }
    $t = (int)($parts['t'] ?? 0);
    if ($t === 0 || abs(time() - $t) > $tolerance) {
        return false;
    }
    $expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
    return hash_equals($expected, $parts['v1'] ?? '');
}

$raw = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_VERGUNNINGWACHT_SIGNATURE'] ?? '';
if (!vw_verify($raw, $sig, getenv('VW_SECRET'))) {
    http_response_code(401);
    exit;
}
http_response_code(200);

CSV-export

Pro en Team downloaden hun meldingen als CSV in het dashboard, voor één zoekopdracht of voor alles. Het bestand is bedoeld voor Excel: puntkomma als scheidingsteken, UTF-8 met BOM en regeleindes met CRLF. Cellen die met =, +, - of @ beginnen krijgen een aanhalingsteken ervoor, zodat Excel er geen formule van maakt.

Een export bevat maximaal 5.000 regels (Pro) of 25.000 regels (Team), nieuwste eerst. Elke export wordt vastgelegd.

Limieten per plan

Er is nog geen openbare API met eigen sleutels. Koppelen kan met de webhook en met de CSV. Heb je daar een vraag over, neem contact op.

Bronnen en privacy

• Bron. De officiële bekendmakingen van KOOP (overheid.nl): gemeenteblad, provinciaal blad, waterschapsblad en Staatscourant. De gegevens zijn open data met een CC0-licentie.
• Wat we bewaren. Titel, datum, soort, fase, locatie, zaaknummer en een link naar de bekendmaking. We bewaren meldingen 24 maanden.
• Wat we niet bewaren. Namen van personen (aanvragers, ondertekenaars, behandelaars), telefoonnummers, e-mailadressen uit de tekst en de volledige tekst van het bericht.
• Openbare pagina's. Tonen alleen aantallen per gemeente en soort, geen huisnummers en geen namen.
• Jouw gebruik. Je gebruikt de meldingen zakelijk. Wat je met een adres doet, zoals contact opnemen, is je eigen verantwoordelijkheid. Lees ook de privacyverklaring en de voorwaarden.
• Fase en soort werk. Door ons afgeleid uit de titel. Ze kunnen afwijken van de bekendmaking. De link naar de bron staat bij elke melding.

Verwijderverzoek

Staat jouw adres in een bekendmaking en wil je dat wij het niet tonen? Stuur het adres of het nummer van de bekendmaking via het contactformulier. We antwoorden binnen 5 werkdagen. We halen de melding uit onze dienst. De bekendmaking zelf blijft op overheid.nl staan, want die is openbaar en wordt door de overheid beheerd.