Overzicht
Met een Signing Secret kan het ontvangende systeem controleren of een verzoek echt van Appical afkomstig is en of de gegevens onderweg niet zijn aangepast.
Het instellen van een Signing Secret is niet verplicht, maar we raden dit wel aan voor elke Webhook, omdat de verstuurde gegevens persoonsgegevens bevatten.
Een Signing Secret instellen
Maak zelf een geheime sleutel aan. Appical genereert deze niet automatisch. Vul de sleutel in bij Signing Secret en deel dezelfde waarde met degene die het ontvangende systeem beheert.
Gebruik een lange, willekeurige sleutel. Kies bijvoorbeeld een wachtwoord van minimaal 32 tekens via een wachtwoordgenerator. De sleutel wordt precies gebruikt zoals je deze invoert, inclusief eventuele spaties.
Bewaar de sleutel op een veilige plek. Na het opslaan wordt de sleutel niet meer getoond, ook niet aan Admins. Sla deze daarom op in bijvoorbeeld een wachtwoordmanager voordat je op Create klikt.
Een Signing Secret wijzigen of verwijderen
Wil je een bestaande sleutel aanpassen of verwijderen? Open dan de Webhook via het potloodicoon.
Een opgeslagen sleutel wordt weergegeven als puntjes. Je hebt vervolgens twee opties:
Replace (Vervangen): Vul de nieuwe sleutel in bij New signing secret en klik op Update.
Remove (Verwijderen): Klik op Remove en vervolgens op Update. Vanaf dat moment worden verzoeken zonder handtekening verstuurd.
📌 Belangrijk:
Een wijziging geldt voor alle verzoeken die na het opslaan worden verstuurd, inclusief het opnieuw versturen van eerdere gebeurtenissen (replays).
Zorg ervoor dat je de sleutel ook direct aanpast in het ontvangende systeem. Anders kunnen de verificaties mislukken.
Wil je voorkomen dat verzoeken tijdelijk worden afgewezen? Stel het ontvangende systeem dan zo in dat het gedurende een korte overgangsperiode zowel de oude als de nieuwe sleutel accepteert.
Welke gegevens verstuurt Appical?
Elk Webhook-verzoek bevat de volgende HTTP-headers:
webhook-id: Een unieke identificatie van het verzoek.webhook-timestamp: Het tijdstip waarop het verzoek is verstuurd.webhook-signature: Wordt toegevoegd wanneer een Signing Secret is ingesteld. Deze bevatv1, gevolgd door een Base64-gecodeerde HMAC-SHA256-handtekening.
Ook testverzoeken en opnieuw verstuurde gebeurtenissen (replays) worden ondertekend.
Bij het opnieuw versturen krijgt het verzoek een nieuwe timestamp en een nieuwe handtekening. Hierdoor kan het verzoek opnieuw worden gecontroleerd op basis van het actuele tijdstip.
Een Webhook-verzoek verifiëren
De handtekening volgt de Standard Webhooks-specificatie.
Het ontvangende systeem controleert het verzoek op de volgende manier:
Lees de oorspronkelijke gegevens. Gebruik de ruwe inhoud van het verzoek (raw request body), precies zoals deze is ontvangen, voordat de JSON wordt verwerkt of opnieuw opgemaakt.
Stel de te ondertekenen tekst samen. Combineer de
webhook-id,webhook-timestampen de oorspronkelijke request body volgens de Standard Webhooks-specificatie, gescheiden door punten (.).Bereken de handtekening. Gebruik HMAC-SHA256 met de Signing Secret die in Appical is ingesteld als sleutel.
Vergelijk de handtekeningen. Codeer het resultaat met Base64 en vergelijk dit met de waarde na
v1,in de headerwebhook-signature. Gebruik hiervoor een vergelijking met constante uitvoeringstijd (constant-time comparison).Controleer de timestamp. Wijs het verzoek af als de
webhook-timestampmeer dan vijf minuten afwijkt van de tijd van het ontvangende systeem.
📌 Belangrijk:
De officiële Standard Webhooks-libraries zijn beschikbaar voor de meeste programmeertalen en kunnen deze controles automatisch uitvoeren.
Deze libraries verwachten de Signing Secret in een specifiek formaat:
whsec_gevolgd door de Base64-codering van de oorspronkelijke sleutel.Gebruik je bijvoorbeeld
mysecretals Signing Secret? Dan moet jewhsec_bXlzZWNyZXQ=doorgeven aan de library.
Als je de oorspronkelijke sleutel zonder deze omzetting doorgeeft, mislukt de verificatie.
→ Voorbeeldgegevens om de verificatie te testen
Gebruik onderstaande voorbeeldgegevens om te controleren of de handtekening correct wordt gevalideerd.
Signing Secret: mysecret
Webhook ID: evt-example
Webhook Timestamp: 1780306200
Request Body: {"event":"user.created","delivered_at":"2026-06-01T09:30:00Z","application_id":123,"data":{"user_id":42}}
Webhook Signature: v1,L3bBkX/a0IVLkzn8uMVxBXQU4K7RxrIRKBbaMmxkOkE=
👉 Heeft dit artikel je geholpen? Laat het ons weten via de knoppen hieronder. Kom je er nog niet uit? Neem dan gerust contact op met ons Supportteam. We helpen je graag verder!