Webhooks

Ontvang real-time notificaties over belangrijke gebeurtenissen zoals quotumwaarschuwingen en API-key expiratie.

// SETUPWebhook instellen

Webhook instellenOntvang real-time notificaties voor belangrijke gebeurtenissen

PostcodeTools kan webhook-notificaties sturen voor quotumwaarschuwingen, API-sleutel expiratie en gebruikspieken. Deze worden automatisch verzonden op basis van uw notificatievoorkeuren.

Ga naar Instellingen > Notificaties in uw dashboard
Schakel de gewenste notificatietypen in
Webhooks worden automatisch verzonden wanneer events optreden

// EVENTSEvent Types

Event TypesBeschikbare webhook-events

Event	Beschrijving
`api_key.created`	Bij het aanmaken van een nieuwe API-sleutel
`api_key.revoked`	Bij het intrekken van een API-sleutel
`usage.spike_detected`	Ongebruikelijke piek in API-gebruik gedetecteerd
`usage.quota_warning`	Quotum nadert de limiet (80%)
`usage.quota_exceeded`	Maandelijks quotum overschreden
`bag.import.completed`	Wanneer een BAG-maandimport voltooid is en de nieuwe data opvraagbaar is

// PAYLOADPayload Formaat

Payload FormaatStructuur van webhook-berichten

Alle webhook-events worden verzonden als JSON met een consistente structuur.

{
  "id": "wh_01HXYZ123456",
  "event": "usage.quota_warning",
  "created_at": "2026-04-15T10:30:00Z",
  "data": {
    "api_key_id": 123,
    "api_key_name": "Production Key",
    "usage_percentage": 80,
    "used": 8000,
    "limit": 10000,
    "period": "monthly"
  }
}

// SIGNATURESignature Verificatie

Signature VerificatieVerifieer dat webhooks van PostcodeTools komen

Elke webhook wordt ondertekend met HMAC-SHA256 op basis van uw webhook-secret en verzonden in twee gelijkwaardige headers.

Signature-headers

Beide headers bevatten dezelfde hex-encoded HMAC-SHA256-digest. Kies degene die uw framework het makkelijkst leest:

X-Signature-256
X-PostcodeTools-Signature

Belangrijk

Verifieer altijd de signature voordat u webhook-data verwerkt. Dit voorkomt spoofing-aanvallen.

PHP

<?php
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_SIGNATURE_256'] ?? '';
$secret = 'your_webhook_secret';

$expectedSignature = hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expectedSignature, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

$event = json_decode($payload, true);
// Process the webhook event...

Python

import hmac
import hashlib
from flask import request

def verify_webhook():
    payload = request.get_data()
    signature = request.headers.get('X-Signature-256', '')
    secret = b'your_webhook_secret'

    expected = hmac.new(secret, payload, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(expected, signature):
        return 'Invalid signature', 401

    event = request.get_json()
    # Process the webhook event...

Node.js

import crypto from 'node:crypto';

export function verifyWebhook(req, res) {
    const payload = req.rawBody;                                 // Buffer of the raw request body
    const signature = req.headers['x-signature-256'] ?? '';
    const secret = 'your_webhook_secret';

    const expected = crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');

    const expectedBuf = Buffer.from(expected, 'hex');
    const actualBuf = Buffer.from(signature, 'hex');

    if (
        expectedBuf.length !== actualBuf.length ||
        !crypto.timingSafeEqual(expectedBuf, actualBuf)
    ) {
        return res.status(401).send('Invalid signature');
    }

    // Process the webhook event...
}

// ROTATIONHet secret roteren

Het secret roterenHoe roteer je het signing-secret van een webhook bij een lek

Gebruik de "Roteer secret"-knop op de detailpagina van de webhook om een nieuw secret te genereren. De nieuwe waarde wordt eenmalig getoond en daarna versleuteld opgeslagen — kopieer hem direct.

Geen overgangsperiode

Rotatie is direct: zodra je op de knop klikt, worden afleveringen ondertekend met het nieuwe secret. Werk je ontvanger eerst bij of accepteer een korte verificatiekloof.

Voeg het nieuwe secret van tevoren toe aan de configuratie van je ontvanger (bijvoorbeeld als tweede geldige waarde naast het huidige).
Klik op "Roteer secret" op de webhook-pagina in PostcodeTools.
Kopieer het nieuwe secret (eenmalig getoond) naar de primaire configuratie van de ontvanger.
Verwijder het oude secret uit de ontvanger zodra nieuwe afleveringen succesvol gevalideerd worden.

// RETRYRetry Beleid

Retry BeleidWat gebeurt er bij mislukte aflevering?

Als uw endpoint niet binnen 30 seconden met een 2xx-status reageert, proberen we het opnieuw.

Eerste poging: Direct

Tweede poging: Na 1 minuut

Derde poging: Na 5 minuten

Vierde poging: Na 30 minuten (laatste)

Let op

Uw endpoint moet binnen 30 seconden reageren, anders wordt het verzoek als mislukt beschouwd.