Developer

Webhooks

Get notified when things happen. NexusKit sends HTTP POST to your endpoints with HMAC-signed payloads — so you can react in real time.

Overview

Webhooks let NexusKit push event data to your server in real time. Instead of polling the API, you register a URL in the dashboard and we'll send an HTTP POST request to that URL whenever an event occurs. Each payload is signed with HMAC-SHA256 so you can verify it came from NexusKit.

API Reference

Events

NexusKit currently supports the following events. Subscribe to specific events or use the wildcard to receive everything:

Event	Description	Example Data
contact.submission	Fired when a contact form submission is received	{ "name": "Jane", "email": "[email protected]" }
onboarding.completed	Fired when a user completes all steps of an onboarding flow	{ "flowId": "flow_abc", "sessionId": "sess_xyz" }
* (wildcard)	Subscribe to all events across your tenant	Any of the above payloads

Payload Format

Every webhook delivery includes the following 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."
    }
  }
}

Field	Type	Description
event	string	The event name (e.g. contact.submission)
timestamp	ISO 8601	When the event occurred
tenantId	string	The tenant this event belongs to
data	object	Event-specific payload (varies by event type)

HMAC-SHA256 Verification

Every webhook request includes an X-NexusKit-Signature header containing an HMAC-SHA256 signature. You should verify this signature to ensure the payload was sent by NexusKit and hasn't been tampered with.

How it works

1NexusKit computes HMAC-SHA256 of the raw request body using your webhook secret
2The hex-encoded signature is sent in the X-NexusKit-Signature header
3Your server re-computes the HMAC using the same secret and compares the two values
4If they match, the payload is authentic — otherwise reject it

Here's a Node.js example that verifies an incoming webhook:

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 });
});

Important: Always use crypto.timingSafeEqual instead of === for signature comparison. The standard equality operator is vulnerable to timing attacks.

Configuration

Set up your webhook endpoints from the NexusKit dashboard:

Navigate to Webhooks

In your dashboard, go to Dashboard → Settings → Webhooks.

Add your endpoint URL

Enter the URL where you want to receive webhook POST requests. Use HTTPS in production.

Select events

Choose which events to subscribe to. You can select individual events or use the * wildcard to receive all events.

Copy your webhook secret

After creating the endpoint, copy the generated webhook secret. Store it securely — you'll need it to verify incoming signatures.

Retry Policy

If your endpoint returns a non-2xx status code or times out, NexusKit will automatically retry the delivery. Retries are managed via BullMQ with exponential backoff:

Attempt	Delay
1st retry	30 seconds
2nd retry	2 minutes
3rd retry	10 minutes
4th retry	1 hour
5th retry (final)	4 hours

After 5 failed attempts, the delivery is marked as failed. You can view delivery logs and retry manually from the dashboard.

Ready to integrate?

Create a free account and set up your first webhook in minutes.

Create free account API Reference