Webhooks & Events
Get notified in real time when reviews are analysed, flagged, or responded to — and integrate ReviewSense with any external system.
Overview
Webhooks let you subscribe to ReviewSense events so your application is notified the moment something happens — without polling the API. When an event occurs, ReviewSense sends an HTTP POST request to your endpoint with a JSON payload describing the event.
Real-time
Events are dispatched within seconds of the triggering action.
Reliable delivery
Automatic retries with exponential back-off on failure.
Signed payloads
HMAC-SHA256 signatures let you verify every request is genuine.
Create a Webhook
You can register webhooks from the AdvikLabs dashboard or programmatically via the API.
Via Dashboard
- Go to Dashboard → ReviewSense → Webhooks → Add Endpoint.
- Enter your Endpoint URL — this must be publicly reachable over HTTPS.
- Select the Events you want to subscribe to (see Event Types below).
- Click Save Endpoint. A Signing Secret is generated — copy it now, it won't be shown again.
Via API
{
"url": "https://yoursite.com/hooks/reviewsense",
"events": [
"review.analysed",
"review.flagged"
],
"description": "Production endpoint"
}
You can register up to 10 webhook endpoints per ReviewSense license. Each endpoint can subscribe to any combination of event types.
Event Types
Subscribe to one or more of the following events:
| Event | Description |
|---|---|
| review.analysed | Fired when sentiment analysis completes for a review. |
| review.flagged | Fired when a review is flagged as potentially inappropriate or spam. |
| review.responded | Fired when an auto-response is posted to a review. |
| review.response_ready | Fired when an AI response draft is ready but not yet posted (awaiting approval). |
| quota.warning | Fired when monthly credit usage reaches 80% of the plan limit. |
| quota.exceeded | Fired when monthly credits are exhausted. |
| webhook.test | Sent manually from the dashboard to verify your endpoint is reachable. |
Payload Format
Every webhook request has the same envelope structure, with the event-specific data nested in the data object.
{
"id": "evt_01JXXXXXXXXXXXXX",
"type": "review.analysed",
"created_at": "2026-04-24T14:30:00Z",
"api_version": "v1",
"data": {
"analysis_id": "rs_ana_01JXXXXXXXXXXXXX",
"review_id": "wc_rev_1042",
"sentiment": "positive",
"score": 87,
"topics": ["shipping", "quality"],
"response_draft": "Thank you for your kind words!..."
}
}
Verifying Signatures
Every webhook request includes a X-ReviewSense-Signature header containing an HMAC-SHA256 signature. Always verify this header before processing the payload.
Never skip signature verification. Without it, any third party could send forged webhook payloads to your endpoint.
The signature is computed as:
HMAC-SHA256(signingSecret, rawRequestBody)Verification example in Node.js:
import crypto from 'node:crypto';
function verifyWebhook(rawBody, signature, secret) {
// rawBody must be the raw Buffer/string, NOT parsed JSON
const expected = crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(signature)
);
}
Use crypto.timingSafeEqual (or your language's equivalent) rather than a simple === comparison to prevent timing attacks.
Retries & Delivery
ReviewSense considers a delivery successful when your endpoint returns a 2xx HTTP status within 10 seconds. Any other response (or a timeout) triggers the retry schedule:
1st retry
5 minutes after failure
2nd retry
30 minutes after 1st retry
3rd retry
2 hours after 2nd retry
4th retry
6 hours after 3rd retry
5th retry (final)
24 hours after 4th retry
After 5 failed attempts the endpoint is marked inactive and no further events are delivered. You can re-enable it and manually resend failed events from Dashboard → ReviewSense → Webhooks → [Endpoint] → Failed Events.
Make your webhook handler idempotent — use the event id field to deduplicate, as the same event may be delivered more than once during retries.
Testing Webhooks
Use the built-in test tool to send a sample webhook.test event to your endpoint without triggering a real analysis.
- Go to Dashboard → ReviewSense → Webhooks → [Your Endpoint].
- Click Send Test Event. A
webhook.testpayload is dispatched immediately. - Check your endpoint's response in the Recent Deliveries log — you'll see the HTTP status, response headers, and response body.
For local development, use a tunnel tool like ngrok or localtunnel to expose your local server to the internet:
# Expose local port 3000
$ ngrok http 3000
# Copy the Forwarding URL and register it as your webhook endpoint
# e.g. https://abc123.ngrok.io/hooks/reviewsense
Delivery succeeds
Your endpoint returned 2xx within 10 s. Event marked as Delivered.
Delivery fails
Non-2xx or timeout. Retry schedule kicks in automatically.