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.
Webhooks are delivered with at-least-once semantics. Your endpoint should be idempotent — use the event_id to deduplicate.

​
Setting Up a Webhook

Register a webhook URL in the NearNode Console under Settings → Webhooks, or via the API.
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.

​
Event Types

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"
  }
}

​
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.

​
Signature Verification

Every webhook request includes an X-NearNode-Signature header. Verify it to ensure the request is authentic and hasn’t been tampered with. The signature is an HMAC-SHA256 of the raw request body using your webhook signing secret. 
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.

​
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. Set up an alert rule to notify you if deliveries start failing.