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.

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