Webhooks

How webhooks work

When NearIQ detects a competitive change, it can POST a JSON payload to a URL you register. This lets you build real-time integrations — send an alert to Slack, trigger a workflow, or update your own dashboard.

Registering a webhook

curl -X POST https://app.neariq.io/api/v1/webhooks \
  -H "X-NearIQ-Key: niq_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/hooks/neariq",
    "events": ["competitor.rating_change", "competitor.review_surge"]
  }'

Webhook URLs must use HTTPS, must not include embedded credentials, and must be publicly routable; localhost, private, link-local, multicast, and reserved network hosts are rejected. NearIQ also re-checks DNS resolution before delivery and deactivates endpoints that resolve to non-public addresses. NearIQ generates and returns the signing secret once when the webhook is created. Supported events are competitor.rating_change, competitor.review_surge, competitor.hours_change, competitor.price_change, competitor.status_change, competitor.website_change, competitor.new_competitor, business.rating_change, business.review_surge, alert.created, api_key.suspended, api_key.reactivated, and api_key.revoked_by_admin.

Payload format

{
  "id": "0bff1ff0-98ab-4c2e-a3ee-4c0b39c090a1",
  "event": "competitor.rating_change",
  "createdAt": "2026-04-27T09:14:22Z",
  "data": {
    "alert": {
      "id": "8e0a8c1d-2a95-4d17-a96b-1ef6b47681c0",
      "type": "rating_change",
      "severity": "opportunity",
      "title": "Rival Pizza dropped from 4.6 to 4.3 stars",
      "description": "Recent reviews suggest service speed is becoming a weakness.",
      "recommendation": "Reply to your latest positive reviews and highlight fast pickup in your next post.",
      "createdAt": "2026-04-27T09:14:22Z",
      "isOwnBusiness": false,
      "metadata": null
    },
    "competitor": {
      "id": "comp_xyz",
      "name": "Rival Pizza",
      "placeId": "ChIJ..."
    }
  }
}

Verifying signatures

NearIQ signs every webhook delivery using HMAC-SHA256. Verify the signature to ensure the request came from NearIQ:

import { createHmac } from 'crypto'

function verifyWebhook(payload: string, timestamp: string, signature: string, secret: string): boolean {
  const expected = createHmac('sha256', secret)
    .update(`${timestamp}.${payload}`)
    .digest('hex')
  return signature === `sha256=${expected}`
}

// In your webhook handler:
const sig = req.headers['x-neariq-signature']
const timestamp = req.headers['x-neariq-timestamp']
const raw = req.rawBody // unparsed request body string
if (!verifyWebhook(raw, timestamp, sig, process.env.NEARIQ_WEBHOOK_SECRET)) {
  return res.status(401).send('Invalid signature')
}

Every delivery includes X-NearIQ-Delivery, X-NearIQ-Event, X-NearIQ-Timestamp, and X-NearIQ-Signature. The signature uses the exact raw request body, prefixed by the timestamp.

Retry behavior

NearIQ retries failed deliveries (non-2xx response or timeout) with exponential backoff:

Retry delays start at about 1 minute
Delays increase exponentially and cap at about 1 hour
Deliveries are attempted up to 8 times

After the final attempt, the delivery is marked dead. The endpoint remains registered so you can fix it without recreating the secret. You can review failed webhook deliveries from the dashboard alert details panel. The panel shows the event type, HTTP response status, retry count, next retry time, and a sanitized payload preview. After fixing your receiver, use the alert’s retry action to queue failed or dead deliveries again.

Webhook management endpoints

All webhook management endpoints require an API key with the webhooks:manage scope and a Growth+ plan.

GET /webhooks — List webhooks

curl https://app.neariq.io/api/v1/webhooks \
  -H "X-NearIQ-Key: niq_your_key_here"

{
  "webhooks": [
    {
      "id": "wh_abc123",
      "url": "https://yourapp.com/hooks/neariq",
      "events": ["competitor.rating_change", "competitor.review_surge"],
      "active": true,
      "createdAt": "2026-04-27T09:14:22Z",
      "lastTriggeredAt": "2026-05-01T12:00:00Z"
    }
  ]
}

POST /webhooks — Register a webhook

curl -X POST https://app.neariq.io/api/v1/webhooks \
  -H "X-NearIQ-Key: niq_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/hooks/neariq",
    "events": ["competitor.rating_change", "alert.created"]
  }'

Field	Type	Required	Notes
`url`	string	yes	Must use HTTPS. No localhost, private, or reserved hosts.
`events`	string[]	yes	At least one event type. See supported events above.

{
  "webhook": {
    "id": "wh_abc123",
    "url": "https://yourapp.com/hooks/neariq",
    "events": ["competitor.rating_change", "alert.created"],
    "active": true,
    "secret": "whsec_abc123...xyz",
    "createdAt": "2026-05-01T12:00:00Z"
  }
}

The secret is returned only on creation. Store it securely — it cannot be retrieved again.

PATCH /webhooks/:id — Update a webhook

curl -X PATCH https://app.neariq.io/api/v1/webhooks/wh_abc123 \
  -H "X-NearIQ-Key: niq_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["competitor.rating_change", "competitor.review_surge", "alert.created"],
    "active": true
  }'

Field	Type	Required	Notes
`url`	string	no	New HTTPS endpoint URL.
`events`	string[]	no	Replace the event list.
`active`	boolean	no	Set `false` to pause deliveries without deleting.

{
  "webhook": {
    "id": "wh_abc123",
    "url": "https://yourapp.com/hooks/neariq",
    "events": ["competitor.rating_change", "competitor.review_surge", "alert.created"],
    "active": true,
    "updatedAt": "2026-05-01T12:30:00Z"
  }
}

DELETE /webhooks/:id — Remove a webhook

curl -X DELETE https://app.neariq.io/api/v1/webhooks/wh_abc123 \
  -H "X-NearIQ-Key: niq_your_key_here"

{
  "deleted": true
}

Deleting a webhook is permanent. Pending deliveries for the endpoint are canceled.

API Reference

Endpoints

Webhooks

How webhooks work

Registering a webhook

Payload format

Verifying signatures

Retry behavior

Webhook management endpoints

GET /webhooks — List webhooks

POST /webhooks — Register a webhook

PATCH /webhooks/:id — Update a webhook

DELETE /webhooks/:id — Remove a webhook

​How webhooks work

​Registering a webhook

​Payload format

​Verifying signatures

​Retry behavior

​Webhook management endpoints

​GET /webhooks — List webhooks

​POST /webhooks — Register a webhook

​PATCH /webhooks/:id — Update a webhook

​DELETE /webhooks/:id — Remove a webhook

How webhooks work

Registering a webhook

Payload format

Verifying signatures

Retry behavior

Webhook management endpoints

GET /webhooks — List webhooks

POST /webhooks — Register a webhook

PATCH /webhooks/:id — Update a webhook

DELETE /webhooks/:id — Remove a webhook