Skip to main content

Webhooks

Receive real-time HTTP POST notifications when events occur in your Onbrix workspace. Use webhooks to keep external systems in sync or trigger custom workflows.

Overview

Webhooks send HTTP POST requests to a URL you specify whenever certain events occur in your Onbrix workspace. Each webhook delivery includes a JSON payload describing the event and the affected record.

You can configure webhooks from Settings → Developer → Webhooks. Each webhook can subscribe to one or more event types and targets a single endpoint URL.

Events

EventDescription
record.createdFired when a new record is created in any module.
record.updatedFired when an existing record is updated (includes field changes).
record.deletedFired when a record is permanently deleted.
deal.stage_changedFired when a deal moves to a different pipeline stage.
task.completedFired when a task is marked as completed.
workflow.triggeredFired when a workflow automation is triggered and executes actions.
project.createdFired when a new project is created (including auto-creation from won deals).
survey.completedFired when a customer submits a CSAT or NPS survey response.
territory.assignedFired when a record is assigned to a territory (manually or via workflow).
achievement.earnedFired when a user earns a gamification achievement or badge.
approval.requestedFired when a new approval request is created for a record.
approval.completedFired when an approval request is approved or rejected.

Payload Format

Every webhook delivery sends a JSON POST body with the following structure:

{
  "event": "record.created",
  "module": "contacts",
  "record": {
    "id": "rec_abc123def456",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "created_at": "2026-03-15T10:30:00Z",
    "updated_at": "2026-03-15T10:30:00Z"
  },
  "timestamp": "2026-03-15T10:30:01Z",
  "teamId": "team_xyz789"
}
FieldTypeDescription
eventstringThe event type that triggered this delivery
modulestringThe module slug (e.g. "contacts", "deals")
recordobjectThe full record data at the time of the event
timestampstringISO 8601 timestamp of when the event occurred
teamIdstringThe team/workspace ID that owns the record

Security

Every webhook delivery includes an X-Webhook-Signature header containing an HMAC-SHA256 signature of the request body. Use this to verify that the request genuinely came from Onbrix.

How to verify the signature

  1. Retrieve your webhook secret from Settings → Developer → Webhooks.
  2. Compute an HMAC-SHA256 hash of the raw request body using your secret as the key.
  3. Compare the computed hash with the value in the X-Webhook-Signature header.
  4. If they match, the request is authentic. If not, reject it.

Node.js example

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const computed = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(computed, 'hex'),
    Buffer.from(signature, 'hex')
  );
}

// In your webhook handler:
const isValid = verifyWebhook(
  rawBody,
  req.headers['x-webhook-signature'],
  process.env.WEBHOOK_SECRET
);

if (!isValid) {
  return res.status(401).json({ error: 'Invalid signature' });
}

Python example

import hmac
import hashlib

def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
    computed = hmac.new(
        secret.encode('utf-8'),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(computed, signature)

# In your webhook handler:
is_valid = verify_webhook(
    request.body,
    request.headers.get('X-Webhook-Signature', ''),
    os.environ['WEBHOOK_SECRET']
)

if not is_valid:
    return JsonResponse({'error': 'Invalid signature'}, status=401)

Retry Policy

If a webhook delivery fails (non-2xx response or timeout), Onbrix will retry with exponential backoff. After 3 consecutive failures, the webhook endpoint is marked as failing and further deliveries are paused until you re-enable it.

AttemptDelayDescription
1st retry30 secondsFirst retry after the initial failed delivery.
2nd retry60 secondsSecond retry with increased backoff.
3rd retry120 secondsFinal retry. If this fails, the webhook is marked as failing.

Your endpoint should respond with a 2xx status code within 10 seconds to be considered successful. We recommend processing webhook payloads asynchronously and returning 200 immediately.

Setup

Follow these steps to configure a webhook endpoint in your Onbrix workspace:

  1. Log in to your Onbrix account at https://app.onbrix.org
  2. Navigate to Settings → Developer → Webhooks
  3. Click Add Webhook
  4. Enter your endpoint URL (must be HTTPS in production)
  5. Select the events you want to subscribe to
  6. Copy the generated webhook secret for signature verification
  7. Click Save — Onbrix will send a test ping to verify your endpoint

Tip: Use a service like webhook.site or ngrok during development to inspect webhook payloads before deploying your production endpoint.