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.
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
| Event | Description |
|---|---|
| record.created | Fired when a new record is created in any module. |
| record.updated | Fired when an existing record is updated (includes field changes). |
| record.deleted | Fired when a record is permanently deleted. |
| deal.stage_changed | Fired when a deal moves to a different pipeline stage. |
| task.completed | Fired when a task is marked as completed. |
| workflow.triggered | Fired when a workflow automation is triggered and executes actions. |
| project.created | Fired when a new project is created (including auto-creation from won deals). |
| survey.completed | Fired when a customer submits a CSAT or NPS survey response. |
| territory.assigned | Fired when a record is assigned to a territory (manually or via workflow). |
| achievement.earned | Fired when a user earns a gamification achievement or badge. |
| approval.requested | Fired when a new approval request is created for a record. |
| approval.completed | Fired 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"
}| Field | Type | Description |
|---|---|---|
| event | string | The event type that triggered this delivery |
| module | string | The module slug (e.g. "contacts", "deals") |
| record | object | The full record data at the time of the event |
| timestamp | string | ISO 8601 timestamp of when the event occurred |
| teamId | string | The 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
- Retrieve your webhook secret from Settings → Developer → Webhooks.
- Compute an HMAC-SHA256 hash of the raw request body using your secret as the key.
- Compare the computed hash with the value in the
X-Webhook-Signatureheader. - 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.
| Attempt | Delay | Description |
|---|---|---|
| 1st retry | 30 seconds | First retry after the initial failed delivery. |
| 2nd retry | 60 seconds | Second retry with increased backoff. |
| 3rd retry | 120 seconds | Final 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:
- Log in to your Onbrix account at
https://app.onbrix.org - Navigate to Settings → Developer → Webhooks
- Click Add Webhook
- Enter your endpoint URL (must be HTTPS in production)
- Select the events you want to subscribe to
- Copy the generated webhook secret for signature verification
- 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.