Real-time Events

Webhooks Documentation

Receive real-time HTTP notifications when events happen in your Sentiments account. Build powerful integrations that react instantly to customer activities.

Quick Start

1

Create an Endpoint

Go to Dashboard → Settings → Webhooks and add a new endpoint. Provide a URL where you want to receive events.

Go to Webhook Settings
2

Subscribe to Events

Select which events you want to receive. You can subscribe to specific events or use "*" to receive all events.

View All Events
3

Verify Signatures

Use your signing secret to verify webhook payloads are genuinely from Sentiments and haven't been tampered with.

Security Guide

Payload Format

All webhook payloads follow a consistent JSON structure with event metadata and the event-specific data.

Headers

HeaderDescription
X-Sentiments-SignatureHMAC-SHA256 signature of the payload
X-Sentiments-TimestampUnix timestamp when the webhook was sent
X-Sentiments-EventThe event type (e.g., advocate.joined)
X-Sentiments-Delivery-IdUnique ID for this delivery attempt

Example Payload

{
  "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"
  }
}

Verifying Webhooks

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.

Verification Steps

  1. Get the raw request body (don't parse it yet)
  2. Compute HMAC-SHA256 of the body using your signing secret
  3. Compare with the X-Sentiments-Signature header
  4. Check the timestamp is recent (within 5 minutes)

Example (Node.js)

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');
});

Retry Behavior

If your endpoint returns a non-2xx status code or times out, we'll automatically retry the delivery with exponential backoff.

Retry Schedule

AttemptDelay
1st retry1 minute
2nd retry5 minutes
3rd retry15 minutes
4th retry1 hour
5th retry (final)4 hours

Auto-disable Protection

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.

Event Types

Reviews

Events related to customer reviews and testimonials

review.submittedA new review/testimonial has been submitted
Live
review.approvedA review has been approved for display
Live
review.rejectedA review has been rejected
Live

Feedback Boards

Events from your feedback and idea boards

idea.createdA new idea has been submitted
Live
idea.status_changedAn idea status has been updated
Live
idea.votedAn idea has received a vote
Live
idea.comment_addedA comment has been added to an idea
Live

Support Desk

Events from your support ticketing system

ticket.createdA new support ticket has been created
Live
ticket.updatedA ticket status or priority has been updated
Live
ticket.resolvedA ticket has been marked as resolved
Live
ticket.message_addedA new message has been added to a ticket
Live

Advocates

Events related to your advocate community

advocate.joinedA new advocate has joined your program
Live
advocate.tier_changedAn advocate tier has changed
Live
advocate.points_earnedAn advocate has earned points
Live

Rewards

Events related to reward redemptions

redemption.requestedAn advocate has requested to redeem a reward
Live
redemption.fulfilledA reward has been fulfilled/delivered
Live

Quests

Events from your gamified quest campaigns

quest.startedAn advocate has started a quest
Live
quest.task_completedAn advocate has completed a quest task
Live
quest.completedAn advocate has completed all tasks in a quest
Live

Polls

Events from your polls

poll.response_submittedA response has been submitted to a poll
Live
poll.completedA poll has reached its target or closing date
Live

Surveys

Events from your surveys

survey.response_submittedA survey response has been submitted
Live
survey.completedA survey has reached its target responses
Live

Forms

Events from your custom forms

form.submission_receivedA form submission has been received
Live

Referrals

Events from your referral program

referral.click_trackedA referral link click has been tracked
Live
referral.conversion_completedA referral has converted (purchase or signup)
Live

Session Replay

Events from session recordings

session.interesting_detectedAn interesting session has been detected (rage clicks, errors)
Coming Soon

Heatmaps

Alert events from heatmap analytics

heatmap.rage_click_spikeRage clicks on a page have exceeded threshold
Live
heatmap.dead_click_detectedDead clicks detected on a new element
Live

Best Practices

Respond Quickly

Return a 2xx response as quickly as possible. Do heavy processing asynchronously after acknowledging receipt.

Handle Idempotency

Use the event ID to handle duplicate deliveries. The same event may be delivered multiple times during retries.

Verify Signatures

Always verify the webhook signature before processing. This protects against spoofed requests.

Use HTTPS

Always use HTTPS endpoints. We don't send webhooks to insecure HTTP URLs in production.

Ready to Get Started?

Create your first webhook endpoint and start receiving real-time notifications.

Configure Webhooks