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
- Scan Events
- Node Events
- Batch Events
Fired when a node is scanned by an end user.
Signature Verification
Every webhook request includes anX-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.
Retry Policy
Failed deliveries (non-2xx response) are retried with exponential backoff:Best Practices
Respond quickly
Respond quickly
Return a
200 response immediately, then process the event asynchronously. Webhook delivery times out after 10 seconds — long-running processing will trigger retries.Handle duplicates
Handle duplicates
Use the
event_id field to deduplicate. Network issues or retries may deliver the same event more than once.Use HTTPS
Use HTTPS
Webhook URLs must use HTTPS. Plain HTTP endpoints are rejected during registration.
Monitor delivery
Monitor delivery
Check the Webhooks page in the Console for delivery logs, response codes, and latency metrics.