Het webhook-contract

Instellen

• Open je site → Bestemmingen.
• Voeg een bestemming toe, zet het type op Webhook en vul je HTTPS-endpoint-URL in.
• Bewaar — LeadButton genereert een signing secret voor de bestemming (zichtbaar op de bewaarde rij).
• Klik Test-payload versturen om een voorbeeldverzoek te ontvangen en je field-mapping te wiren.

Elke actieve bestemming ontvangt elke lead, dus je kunt e-mail- en webhook-bestemmingen vrij combineren.

Het verzoek

Leads worden afgeleverd als een HTTP POST naar je URL:

POST <your webhook url>
Content-Type: application/json
User-Agent: LeadButton-Webhook/1.0
X-LeadButton-Signature: sha256=<hmac-sha256-hex>

De payload is een platte JSON. fields is een plat object van de ingediende formuliervelden (alle waarden zijn strings); widget_key, page_url en referrer kunnen null zijn.

{
  "lead_id": "3e9a4a1e-7a44-4a1e-9a63-1f2ab33c9d10",
  "space_code": "66a3ba5433a10",
  "widget_key": "contactbot",
  "fields": {
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "message": "I'd like more information."
  },
  "page_url": "https://example.com/contact",
  "referrer": "https://www.google.com/",
  "created_at": "2026-07-07T12:00:00.000Z"
}

Test-payloads (van de knop Test-payload versturen) dragen één extra sleutel, "test": true. Echte leads bevatten die nooit — filter erop als je ontvanger tests moet negeren.

De handtekening verifiëren

Elk verzoek is ondertekend. De X-LeadButton-Signature-header is sha256= gevolgd door de hex HMAC-SHA256 van de ruwe request-body-bytes, met het signing secret van de bestemming. Verifieer altijd tegen de ruwe body — parsen en opnieuw serialiseren kan de bytes veranderen.

const { createHmac, timingSafeEqual } = require('node:crypto');

function verify(rawBody /* Buffer or string */, signatureHeader, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  return (
    signatureHeader.length === expected.length &&
    timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected))
  );
}

Uitgewerkt voorbeeld (ook vastgezet als de cross-runtime testvector in de LeadButton-codebase):

secret:    lb_test_secret
body:      {"id":"7f9c24e5-2c31-4a4b-99d6-99d09d4c8a3b","space":"testspace","widget_key":"contactbot","fields":{"name":"Ada"},"page_url":"https://example.com/","referrer":null,"created_at":"2026-01-01T00:00:00.000Z"}
signature: sha256=b6d180e7fc6a11bae18b2e806465548e3b9d8480553aac0b16338566d767955d

Levering-semantiek

• Time-out: 5 seconden per poging.
• Retries: één retry (na ~1 s) bij time-out, netwerkfouten, 429 en 5xx. Andere 4xx worden als permanente afwijzing behandeld en niet opnieuw geprobeerd.
• At-least-once: door de retry kan je endpoint dezelfde lead twee keer ontvangen — dedupliceer op lead_id als dat uitmaakt.
• Bevestig snel: elke 2xx telt als afgeleverd; antwoord vóór je trage werk doet. Redirects worden niet gevolgd en de response-body wordt genegeerd.
• URL-eisen: alleen https://; private hosts/adressen (localhost, RFC1918, .local/.internal, link-local) worden geweigerd.

Zapier / Make

• Zapier: gebruik de Webhooks by Zapier-trigger met Catch Hook; plak de gegenereerde Catch Hook-URL als je bestemmings-URL en klik dan Test-payload versturen.
• Make (Integromat): voeg een Webhooks → Custom webhook-module toe, kopieer het adres als bestemmings-URL, klik Redetermine data structure en dan Test-payload versturen.

Geen van beide platforms verifieert standaard handtekeningen; de payload draagt er wel één als je die in een code-stap wilt checken.