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
- Click Add webhook
- Enter your endpoint URL: the HTTPS URL that receives the events
- Keep All events on, or turn it off and choose the events you want
- 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
| Event | Triggered when |
|---|---|
consumer.registered | A consumer registers a product |
consumer.scanned | A consumer scans a product QR code |
consumer.chat_completed | An AI Support Chat session ends |
consumer.feedback_submitted | A consumer submits feedback |
consumer.unsubscribed | A consumer unsubscribes from emails |
consumer.chat_escalated | The AI hands a chat over to your team |
consumer.conversation_created | A new helpdesk conversation starts |
consumer.conversation_replied | A customer replies in a helpdesk conversation |
consumer.claim_submitted | A customer submits a warranty claim |
consumer.claim_updated | A warranty claim changes status |
consumer.health_changed | An owner's sentiment changes (Happy, Neutral, At risk) |
product.created | A product is created |
product.updated | A product is changed |
product.status_changed | A product goes live, back to draft, or is archived |
product.deleted | A 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 withrole,textandat),topic,product(id,name,brand,model) andcustomer(email,name)consumer.claim_submitted:claim_number,subject,description,priority,submitted_atandcustomer(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
tis when the delivery was sent (Unix seconds)v1is the HMAC-SHA256 of{t}.{raw request body}, using your signing secret, in hex
To verify a delivery:
- Read the raw request body (before parsing the JSON)
- Compute HMAC-SHA256 of the string
t + "." + bodywith your signing secret - Compare it with
v1using a constant-time comparison - Reject the delivery if
tis 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-Signatureheader (HMAC-SHA256 of the body alone) is still sent until April 2027. Switch toVeribl-Signaturebefore then.
Test a webhook
- Open your webhook endpoint
- Click Send Test
- Veribl sends a test payload to your endpoint
- Check the delivery log to see the response
Delivery logs
View the delivery history for each endpoint:
- Click on a webhook endpoint
- Click Deliveries to see all delivery attempts
- 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?