Webhooks

Webhooks allow you to receive HTTP notifications when events happen in your BlueSuite workspace. Instead of polling for changes, webhooks push data to your server in real-time.

How Webhooks Work

You subscribe to specific events (e.g., new_request)
When that event occurs, BlueSuite sends a POST request to your URL
Your server processes the webhook payload
BlueSuite retries failed deliveries automatically

Available Events

Event	Description
`new_request`	A new customer request is created
`request_updated`	An existing request is updated
`new_contact`	A new contact is added
`new_quote`	A new quote is created
`quote_accepted`	A quote is accepted by the customer
`new_job`	A new job is created
`new_invoice`	A new invoice is created
`invoice_sent`	An invoice is sent to the customer
`invoice_paid`	An invoice is marked as paid

Webhook Payload

All webhook payloads follow this structure:

{
  "event": "new_request",
  "workspace_id": 123,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "id": 456,
    // Event-specific data
  },
  "meta": {
    "webhook_id": "wh_abc123",
    "delivery_attempt": 1,
    "link": "https://app.bluesuite.com/requests/456"
  }
}

Payload Fields

Field	Type	Description
`event`	string	The event type that triggered the webhook
`workspace_id`	number	Your workspace ID
`timestamp`	string	ISO 8601 timestamp of when the event occurred
`data`	object	Event-specific data (the resource that changed)
`data.id`	number	ID of the affected resource
`meta.webhook_id`	string	Unique identifier for this webhook
`meta.delivery_attempt`	number	Which delivery attempt this is (1, 2, 3...)
`meta.link`	string	Direct link to the resource in BlueSuite

Retry Policy

If your webhook endpoint returns a non-2xx status code, BlueSuite will retry delivery:

Attempt 1: Immediate
Attempt 2: After 5 minutes
Attempt 3: After 30 minutes
Attempt 4: After 2 hours
Attempt 5: After 24 hours

After 5 failed attempts, the webhook is marked as failed and no further retries occur.

Security

Verifying Webhook Signatures

BlueSuite signs webhook payloads using HMAC-SHA256. Verify signatures to ensure webhooks are authentic:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-bluesuite-signature'];

  if (!verifyWebhookSignature(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook...
  res.status(200).send('OK');
});

Best Practices

Respond quickly - Return a 200 response immediately, then process async
Handle duplicates - Use meta.webhook_id to deduplicate
Verify signatures - Always validate the X-BlueSuite-Signature header
Use HTTPS - Only use secure URLs for webhook endpoints

API Endpoints

Create a new webhook subscription.

POST /api/webhooks/subscribe

Required Scope: webhooks:write

Request Body:

{
  "trigger_event": "new_request",
  "webhook_url": "https://your-site.com/webhook"
}

Response:

{
  "success": true,
  "subscription": {
    "id": 123,
    "trigger_event": "new_request",
    "webhook_url": "https://your-site.com/webhook",
    "is_active": true,
    "created_at": "2024-01-15T10:30:00.000Z"
  }
}

List Subscriptions

Get all webhook subscriptions for your workspace.

GET /api/webhooks/list

Required Scope: webhooks:read

Query Parameters:

Parameter	Type	Description
`trigger_event`	string	Optional. Filter by event type

Response:

{
  "success": true,
  "subscriptions": [
    {
      "id": 123,
      "trigger_event": "new_request",
      "webhook_url": "https://your-site.com/webhook",
      "is_active": true,
      "created_at": "2024-01-15T10:30:00.000Z",
      "last_triggered_at": "2024-01-20T14:22:00.000Z"
    }
  ],
  "count": 1
}

Unsubscribe

Delete a webhook subscription.

DELETE /api/webhooks/unsubscribe

Required Scope: webhooks:write

Request Body:

{
  "subscription_id": 123
}

Response:

{
  "success": true,
  "message": "Webhook subscription deleted successfully"
}

Example: New Request Webhook

When a new customer request is submitted, you'll receive:

{
  "event": "new_request",
  "workspace_id": 123,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "id": 456,
    "name": "John Smith",
    "email": "john@example.com",
    "phone": "555-123-4567",
    "service_type": "Window Cleaning",
    "message": "I need a quote for window cleaning",
    "status": "new",
    "created_at": "2024-01-15T10:30:00.000Z"
  },
  "meta": {
    "webhook_id": "wh_abc123def456",
    "delivery_attempt": 1,
    "link": "https://app.bluesuite.com/requests/456"
  }
}

On this page