Ontwikkelaar

Webhooks

Ontvang meldingen zodra er iets gebeurt. NexusKit stuurt HTTP POST naar uw endpoints met HMAC-ondertekende payloads — zodat u in realtime kunt reageren.

Overzicht

Met webhooks kan NexusKit event-data in realtime naar uw server pushen. In plaats van de API te pollen, registreert u een URL in het Dashboard en sturen wij een HTTP POST-verzoek naar die URL zodra een event plaatsvindt. Elke payload is ondertekend met HMAC-SHA256, zodat u kunt verifiëren dat deze afkomstig is van NexusKit.

API-referentie

Events

NexusKit ondersteunt momenteel de volgende events. Abonneer op specifieke events of gebruik de wildcard om alles te ontvangen:

Event	Beschrijving	Voorbeelddata
contact.submission	Wordt geactiveerd wanneer een contactformulier-inzending wordt ontvangen	{ "name": "Jane", "email": "[email protected]" }
onboarding.completed	Wordt geactiveerd wanneer een gebruiker alle stappen van een onboarding-flow voltooit	{ "flowId": "flow_abc", "sessionId": "sess_xyz" }
* (wildcard)	Abonneer op alle events binnen uw Tenant	Elk van de bovenstaande payloads

Payload-formaat

Elke webhook-aflevering bevat de volgende JSON-body:

{
  "event": "contact.submission",
  "timestamp": "2026-08-21T14:30:00.000Z",
  "tenantId": "tnt_abc123",
  "data": {
    "submissionId": "sub_xyz789",
    "formId": "frm_abc123",
    "payload": {
      "name": "Jane Doe",
      "email": "[email protected]",
      "message": "Interested in your services."
    }
  }
}

Veld	Type	Beschrijving
event	string	De naam van het event (bijv. contact.submission)
timestamp	ISO 8601	Wanneer het event plaatsvond
tenantId	string	De Tenant waartoe dit event behoort
data	object	Event-specifieke payload (verschilt per event-type)

HMAC-SHA256-verificatie

Elk webhook-verzoek bevat een X-NexusKit-Signature-header met een HMAC-SHA256-handtekening. U dient deze handtekening te verifiëren om zeker te zijn dat de payload door NexusKit is verstuurd en niet is gemanipuleerd.

Hoe het werkt

1NexusKit berekent HMAC-SHA256 van de ruwe request-body met uw webhook secret
2De hexadecimaal gecodeerde handtekening wordt verstuurd in de X-NexusKit-Signature-header
3Uw server berekent de HMAC opnieuw met hetzelfde secret en vergelijkt de twee waarden
4Komen ze overeen, dan is de payload authentiek — zo niet, wijs deze dan af

Hier is een Node.js-voorbeeld dat een binnenkomende webhook verifieert:

import crypto from 'node:crypto';

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

// Express / Connect middleware example
app.post('/webhooks/nexuskit', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-nexuskit-signature'];
  const secret = process.env.NEXUSKIT_WEBHOOK_SECRET;

  if (!verifyWebhookSignature(req.body, signature, secret)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(req.body);
  console.log('Verified webhook:', event.event);

  // Process the event...
  res.status(200).json({ received: true });
});

Belangrijk: Gebruik altijd crypto.timingSafeEqual in plaats van === voor het vergelijken van handtekeningen. De standaard gelijkheidsoperator is kwetsbaar voor timing-aanvallen.

Configuratie

Stel uw webhook-endpoints in vanuit het NexusKit-dashboard:

Ga naar Webhooks

Ga in uw Dashboard naar Dashboard → Settings → Webhooks.

Voeg uw endpoint-URL toe

Voer de URL in waarop u webhook-POST-verzoeken wilt ontvangen. Gebruik HTTPS in productie.

Selecteer events

Kies op welke events u wilt abonneren. U kunt afzonderlijke events selecteren of de *-wildcard gebruiken om alle events te ontvangen.

Kopieer uw webhook secret

Kopieer na het aanmaken van het endpoint het gegenereerde webhook secret. Bewaar het veilig — u hebt het nodig om binnenkomende handtekeningen te verifiëren.

Retrybeleid

Geeft uw endpoint een niet-2xx statuscode terug of loopt het verzoek vast, dan probeert NexusKit de aflevering automatisch opnieuw. Retries worden beheerd via BullMQ met exponentiële backoff:

Poging	Vertraging
1e retry	30 seconden
2e retry	2 minuten
3e retry	10 minuten
4e retry	1 uur
5e retry (laatste)	4 uur

Na 5 mislukte pogingen wordt de aflevering als mislukt gemarkeerd. U kunt afleveringslogs bekijken en handmatig opnieuw proberen vanuit het Dashboard.

Klaar om te integreren?

Maak een gratis account aan en zet binnen enkele minuten uw eerste webhook op.

Gratis account aanmaken API-referentie