Skip to main content
Webhooks let NearIQ push events to your server the moment something changes — a competitor’s rating drops, your own listing gets a review surge, or a new alert is created. Instead of polling the API, you register an HTTPS endpoint and NearIQ delivers a signed JSON payload to it automatically. You can register up to 10 webhook endpoints per account.

​
GET /api/v1/webhooks

Returns all registered webhook endpoints on your account. 
curl https://neariq.io/api/v1/webhooks \
  -H "X-NearIQ-Key: niq_live_..."

​
Response fields

​
data
object[]
required
​
count
number
required
Total number of registered endpoints.

​
POST /api/v1/webhooks

Registers a new webhook endpoint. The response includes a secret that you use to verify incoming payloads — save it immediately, as it is never shown again. 
curl -X POST https://neariq.io/api/v1/webhooks \
  -H "X-NearIQ-Key: niq_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/neariq",
    "events": ["competitor.rating_change", "alert.created"]
  }'

​
Request body

​
url
string
required
The HTTPS (or HTTP) URL NearIQ should POST events to. Must be a valid URL.
​
events
string[]
required
One or more event types to subscribe to. See supported events below.

​
Supported events

EventTriggered when
competitor.rating_changeA tracked competitor’s Google rating changes
competitor.review_surgeA tracked competitor receives an unusual spike in reviews
competitor.hours_changeA tracked competitor updates their opening hours
competitor.website_changeA tracked competitor changes their website URL
competitor.new_competitorA new competitor is detected in your area
business.rating_changeYour own Google rating changes
business.review_surgeYour own listing receives a review spike
alert.createdAny new alert is created for your account

​
Response fields

​
id
string
required
Unique ID for the new endpoint.
​
url
string
required
The registered URL.
​
events
string[]
required
The subscribed event types.
​
active
boolean
required
Always true for a newly created endpoint.
​
secret
string
required
Signing secret prefixed with whsec_. Used to verify the X-NearIQ-Signature header on incoming deliveries. This field is only returned once.
​
createdAt
string
required
ISO 8601 creation timestamp.
​
note
string
required
A reminder that the secret will not be shown again.
Store your whsec_... secret in a secure environment variable. If you lose it, delete this endpoint and create a new one.

​
PATCH /api/v1/webhooks/:id

Updates a webhook endpoint. You can change the URL, update the subscribed events, or toggle the endpoint on and off. Only include the fields you want to change. 
curl -X PATCH https://neariq.io/api/v1/webhooks/wh_abc123 \
  -H "X-NearIQ-Key: niq_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

​
Path parameters

​
id
string
required
The webhook endpoint ID to update.

​
Request body

​
url
string
New delivery URL. Must be a valid HTTP or HTTPS URL.
​
events
string[]
Replacement list of subscribed events. Must be a non-empty array of valid event types.
​
active
boolean
Set to false to pause deliveries without deleting the endpoint.

​
Response

Returns the updated WebhookEndpoint object (same shape as the GET /webhooks list items).

​
DELETE /api/v1/webhooks/:id

Permanently deletes a webhook endpoint. In-flight deliveries may still be attempted. Returns 204 No Content on success. 
curl -X DELETE https://neariq.io/api/v1/webhooks/wh_abc123 \
  -H "X-NearIQ-Key: niq_live_..."

​
Path parameters

​
id
string
required
The webhook endpoint ID to delete.

​
Verifying webhook payloads

Every delivery includes an X-NearIQ-Signature header with a sha256=<hmac> value. You should always verify this signature before processing the payload. NearIQ computes the HMAC-SHA256 of the raw request body using your endpoint’s whsec_... secret as the key. 
import crypto from 'crypto'

export function verifyNearIQSignature(
  rawBody: string,
  signatureHeader: string,
  secret: string
): boolean {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  )
}

// Express.js example
app.post('/hooks/neariq', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-neariq-signature'] as string
  if (!verifyNearIQSignature(req.body.toString(), sig, process.env.NEARIQ_WEBHOOK_SECRET!)) {
    return res.status(401).send('Invalid signature')
  }
  const event = JSON.parse(req.body.toString())
  console.log('Event received:', event.type)
  res.sendStatus(200)
})
Each delivery also includes an X-NearIQ-Event header containing the event type (e.g., competitor.rating_change), which you can use to route events without parsing the body first.