Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.vendaze.com/llms.txt

Use this file to discover all available pages before exploring further.

Webhooks allow Vendaze to notify your application when events occur in the workspace. Instead of polling continuously, your server receives an HTTP notification as soon as something changes.
Webhooks are configured by the Vendaze customer in the platform dashboard, not via the public API. This guide explains how to receive and validate the notifications.

​
How it works

  1. The Vendaze customer configures a webhook in the dashboard: sets the destination URL and desired events
  2. Vendaze generates a unique webhook_secret for that endpoint
  3. When an event occurs, Vendaze sends a POST to the configured URL with a signed payload
  4. Your server validates the signature and processes the event

​
Available events

EventWhen it occurs
person.createdA new person is created
person.updatedA person is updated
company.createdA new company is created
company.updatedA company is updated
deal.createdA new deal is created
deal.updatedA deal is updated
activity.createdA new activity is logged
activity.updatedAn activity is updated
task.createdA new task is created
task.updatedA task is updated
product.createdA new product is created
product.updatedA product is updated

​
Payload format

{
  "event": "person.created",
  "workspace_slug": "customer-workspace",
  "timestamp": "2026-05-26T14:00:00Z",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "full_name": "Ana Costa",
    "emails": [{ "email": "ana@company.com", "reminder": "work" }],
    "created_at": "2026-05-26T14:00:00Z"
  }
}

​
Validate the signature

Each delivery is signed with HMAC-SHA256 using the webhook_secret. Validate before processing. Headers sent by Vendaze: 
X-Vendaze-Signature: sha256=abc123...
X-Vendaze-Timestamp: 1748000000
Node.js validation: 
const crypto = require('crypto');

function isValidSignature(body, timestamp, receivedSignature, secret) {
  // Reject payloads older than 5 minutes
  const now = Math.floor(Date.now() / 1000);
  if (now - parseInt(timestamp) > 300) return false;

  const message = `${timestamp}.${JSON.stringify(body)}`;
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(message).digest('hex');

  return crypto.timingSafeEqual(Buffer.from(receivedSignature), Buffer.from(expected));
}
Reject payloads with a timestamp older than 5 minutes. This protects against replay attacks.

​
Retry policy

If your server does not return a 2xx status within 10 seconds, Vendaze retries:
AttemptWait
21 minute
35 minutes
430 minutes
52 hours
After 5 consecutive failures, the endpoint is marked as suspended. The customer reactivates it in the dashboard.

​
Best practices

  • Respond quickly: return 200 immediately and process in the background.
  • Be idempotent: the same event may arrive more than once. Use the payload id to deduplicate.
  • Keep logs: store received payloads to simplify debugging and auditing.