Veribl logo
Available with the API & webhooks add-on

Webhooks

Updated

Webhooks send real-time notifications to your systems when events happen in Veribl — like a new registration or product scan.

Webhooks are part of the API & webhooks add-on ($79 a month, included in Enterprise). See Billing and plans.

Access Webhooks

Go to Settings › Webhooks, next to API keys.

Create a webhook endpoint

  1. Click Add webhook
  2. Enter your endpoint URL: the HTTPS URL that receives the events
  3. Keep All events on, or turn it off and choose the events you want
  4. Click Add

Click a webhook to see its signing secret and recent deliveries, send a test event, turn it off, or edit it.

Supported events

EventTriggered when
consumer.registeredA consumer registers a product
consumer.scannedA consumer scans a product QR code
consumer.chat_completedAn AI Support Chat session ends
consumer.feedback_submittedA consumer submits feedback
consumer.unsubscribedA consumer unsubscribes from emails
consumer.chat_escalatedThe AI hands a chat over to your team
consumer.conversation_createdA new helpdesk conversation starts
consumer.conversation_repliedA customer replies in a helpdesk conversation
consumer.claim_submittedA customer submits a warranty claim
consumer.claim_updatedA warranty claim changes status
consumer.health_changedAn owner's sentiment changes (Happy, Neutral, At risk)
product.createdA product is created
product.updatedA product is changed
product.status_changedA product goes live, back to draft, or is archived
product.deletedA product is deleted

Webhook payload

Each webhook delivery sends a JSON payload with:

  • id: the event's unique id (evt_…). It stays the same on every retry, so use it to skip events you've already handled
  • event: the event type (e.g., consumer.registered)
  • timestamp: when the event occurred
  • data: event-specific data (consumer details, product info, etc.)

Two events carry everything a helpdesk needs to open a ticket, without calling back:

  • consumer.chat_escalated: transcript (the last 50 messages, each with role, text and at), topic, product (id, name, brand, model) and customer (email, name)
  • consumer.claim_submitted: claim_number, subject, description, priority, submitted_at and customer (email, name)

Security: verify the signature

When you create an endpoint, Veribl generates a signing secret. Every delivery carries a Veribl-Signature header:

Veribl-Signature: t=1792600000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
  • t is when the delivery was sent (Unix seconds)
  • v1 is the HMAC-SHA256 of {t}.{raw request body}, using your signing secret, in hex

To verify a delivery:

  1. Read the raw request body (before parsing the JSON)
  2. Compute HMAC-SHA256 of the string t + "." + body with your signing secret
  3. Compare it with v1 using a constant-time comparison
  4. Reject the delivery if t is more than 5 minutes old. This stops anyone from replaying a delivery they captured
import crypto from 'node:crypto';
 
function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Each delivery also includes Veribl-Event-Id (the event's id), X-Webhook-Event (the event type) and X-Webhook-Delivery (this attempt's id).

Older integrations: the previous X-Webhook-Signature header (HMAC-SHA256 of the body alone) is still sent until April 2027. Switch to Veribl-Signature before then.

Test a webhook

  1. Open your webhook endpoint
  2. Click Send Test
  3. Veribl sends a test payload to your endpoint
  4. Check the delivery log to see the response

Delivery logs

View the delivery history for each endpoint:

  1. Click on a webhook endpoint
  2. Click Deliveries to see all delivery attempts
  3. Each entry shows: event type, timestamp, response status, and payload

Retry behavior

If your endpoint doesn't answer with a 2xx status within 10 seconds, Veribl tries again after 15 minutes, 1 hour, 3 hours, 6 hours, 12 hours, and then every 24 hours: 8 attempts over about 3 days. Every attempt carries the same event id, so your server can safely ignore one it has already processed.

Was this article helpful?

More ways to get help

  • Support

    Can't find the answer? Send us your question and the product or page it's about.

    Contact support
  • Specialists

    Get hands-on help with setup, migrating manuals, or designing your product pages.

    Book a call
  • Enterprise

    Dedicated onboarding, custom integrations, and regulatory guidance for large teams.

    Contact enterprise