Receive real-time HTTP notifications when events happen in your Sentiments account. Build powerful integrations that react instantly to customer activities.
Go to Dashboard → Settings → Webhooks and add a new endpoint. Provide a URL where you want to receive events.
Go to Webhook SettingsSelect which events you want to receive. You can subscribe to specific events or use "*" to receive all events.
View All EventsUse your signing secret to verify webhook payloads are genuinely from Sentiments and haven't been tampered with.
Security GuideAll webhook payloads follow a consistent JSON structure with event metadata and the event-specific data.
| Header | Description |
|---|---|
| X-Sentiments-Signature | HMAC-SHA256 signature of the payload |
| X-Sentiments-Timestamp | Unix timestamp when the webhook was sent |
| X-Sentiments-Event | The event type (e.g., advocate.joined) |
| X-Sentiments-Delivery-Id | Unique ID for this delivery attempt |
{
"id": "evt_abc123def456",
"type": "advocate.joined",
"created": "2024-01-15T10:30:00.000Z",
"business_id": "biz_xyz789",
"data": {
"advocate_id": "adv_123",
"email": "john@example.com",
"name": "John Doe",
"tier": "bronze",
"source": "invite"
}
}Always verify webhook signatures to ensure payloads are from Sentiments and haven't been modified. Each endpoint has a unique signing secret that you can find in your webhook settings.
const crypto = require('crypto');
function verifyWebhook(payload, signature, secret) {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}
// In your webhook handler:
app.post('/webhooks/sentiments', (req, res) => {
const signature = req.headers['x-sentiments-signature'];
const timestamp = req.headers['x-sentiments-timestamp'];
const rawBody = req.rawBody; // Use raw body, not parsed JSON
// Check timestamp is within 5 minutes
const age = Date.now() / 1000 - parseInt(timestamp);
if (age > 300) {
return res.status(401).send('Webhook expired');
}
if (!verifyWebhook(rawBody, signature, WEBHOOK_SECRET)) {
return res.status(401).send('Invalid signature');
}
const event = JSON.parse(rawBody);
// Process the event...
res.status(200).send('OK');
});If your endpoint returns a non-2xx status code or times out, we'll automatically retry the delivery with exponential backoff.
| Attempt | Delay |
|---|---|
| 1st retry | 1 minute |
| 2nd retry | 5 minutes |
| 3rd retry | 15 minutes |
| 4th retry | 1 hour |
| 5th retry (final) | 4 hours |
If an endpoint fails 10 consecutive deliveries, it will be automatically disabled to prevent continued failures. You can re-enable it from your webhook settings after fixing the issue.
Events related to customer reviews and testimonials
review.submittedA new review/testimonial has been submittedreview.approvedA review has been approved for displayreview.rejectedA review has been rejectedEvents from your feedback and idea boards
idea.createdA new idea has been submittedidea.status_changedAn idea status has been updatedidea.votedAn idea has received a voteidea.comment_addedA comment has been added to an ideaEvents from your support ticketing system
ticket.createdA new support ticket has been createdticket.updatedA ticket status or priority has been updatedticket.resolvedA ticket has been marked as resolvedticket.message_addedA new message has been added to a ticketEvents related to your advocate community
advocate.joinedA new advocate has joined your programadvocate.tier_changedAn advocate tier has changedadvocate.points_earnedAn advocate has earned pointsEvents related to reward redemptions
redemption.requestedAn advocate has requested to redeem a rewardredemption.fulfilledA reward has been fulfilled/deliveredEvents from your gamified quest campaigns
quest.startedAn advocate has started a questquest.task_completedAn advocate has completed a quest taskquest.completedAn advocate has completed all tasks in a questEvents from your polls
poll.response_submittedA response has been submitted to a pollpoll.completedA poll has reached its target or closing dateEvents from your surveys
survey.response_submittedA survey response has been submittedsurvey.completedA survey has reached its target responsesEvents from your custom forms
form.submission_receivedA form submission has been receivedEvents from your referral program
referral.click_trackedA referral link click has been trackedreferral.conversion_completedA referral has converted (purchase or signup)Events from session recordings
session.interesting_detectedAn interesting session has been detected (rage clicks, errors)Alert events from heatmap analytics
heatmap.rage_click_spikeRage clicks on a page have exceeded thresholdheatmap.dead_click_detectedDead clicks detected on a new elementReturn a 2xx response as quickly as possible. Do heavy processing asynchronously after acknowledging receipt.
Use the event ID to handle duplicate deliveries. The same event may be delivered multiple times during retries.
Always verify the webhook signature before processing. This protects against spoofed requests.
Always use HTTPS endpoints. We don't send webhooks to insecure HTTP URLs in production.
Create your first webhook endpoint and start receiving real-time notifications.
Configure Webhooks