Skip to main content
Webhooks push scan data to your server in real time. Every time a node is scanned, NearNode fires an HTTP POST to your registered endpoint. Pipe scan events into your data warehouse, CRM, alerting system, or n8n automation.
Webhooks are delivered with at-least-once semantics. Your endpoint should be idempotent — use the event_id to deduplicate.

​
Setting Up a Webhook

1

Add your endpoint URL

Enter the HTTPS URL where you want to receive events (e.g., https://api.yourapp.com/webhooks/nearnode).
2

Select event types

Choose which events to subscribe to. You can listen to all events or filter by type.
3

Copy your signing secret

A unique secret is generated for each webhook. Store it securely — you’ll use it to verify signatures.
4

Test the connection

Click Send Test Event to verify your endpoint responds with a 200 status.
Ops Tip: You can configure webhooks visually in the Dashboard under Settings → Webhooks — no API calls required.

​
Supported Events

Fired when a node is scanned by an end user.
EventDescription
scan.createdA node was scanned (any function type)
scan.redirectA redirect was followed
scan.vcard_downloadA vCard was downloaded
scan.blockedScan was blocked by kill switch
{
  "event": "scan.created",
  "event_id": "evt_a1b2c3d4",
  "timestamp": "2026-02-09T14:30:00.000Z",
  "data": {
    "node_slug": "o1ulpplq",
    "node_id": "node_abc123...",
    "city": "Zurich",
    "country": "CH",
    "device_type": "mobile",
    "user_agent": "Mozilla/5.0 (iPhone; ...)",
    "ip_address": "203.0.113.42",
    "variant": null,
    "session_id": "sid_x7y8z9"
  }
}

​
Signature Verification

Every webhook request includes an X-NearNode-Signature header — an HMAC-SHA256 of the raw request body signed with your webhook secret. Always verify signatures to ensure the request is authentic and hasn’t been tampered with. 
const crypto = require('crypto');

function verifyWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

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

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

  if (!verifyWebhook(req.body, signature, secret)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  console.log(`Received ${event.event} for ${event.data.node_slug}`);

  res.status(200).send('OK');
});
Always use timing-safe comparison (like crypto.timingSafeEqual or hmac.compare_digest) to prevent timing attacks on signature verification.

​
Retry Policy

Failed deliveries (non-2xx response) are retried with exponential backoff:
AttemptDelayTotal elapsed
1st retry1 minute1 min
2nd retry5 minutes6 min
3rd retry30 minutes36 min
After 3 consecutive failures, the webhook is marked as failing. It remains active but a warning is shown in the Console. Fix your endpoint and click Retry Failed to re-deliver missed events.

​
Best Practices

Return a 200 response immediately, then process the event asynchronously. Webhook delivery times out after 10 seconds — long-running processing will trigger retries.
Use the event_id field to deduplicate. Network issues or retries may deliver the same event more than once.
Webhook URLs must use HTTPS. Plain HTTP endpoints are rejected during registration.
Check the Webhooks page in the Console for delivery logs, response codes, and latency metrics.