Webhooks
Configure outgoing webhooks to receive real-time HTTP notifications when events occur in your ProBeya organization.
Overview
Webhooks let you receive real-time HTTP POST notifications when specific events occur in your ProBeya organization. Use webhooks to integrate with external systems, trigger CI/CD pipelines, update data warehouses, or build custom notification workflows.
Creating a Webhook
Open Webhook Settings
Navigate to Settings > Webhooks in your organization admin panel.
Click Create Webhook
Click the Create Webhook button.
Configure the Webhook
- URL — the HTTPS endpoint that will receive POST requests. Must be a valid, publicly accessible URL.
- Events — select one or more event types to subscribe to (see the events table below).
Copy the Signing Secret
A cryptographically secure signing secret (256 bits / 64 hex characters) is generated automatically. Copy it immediately — you will need it to verify webhook signatures.
The signing secret is displayed once at creation time. Store it securely in your receiving application’s environment variables.
Supported Events
| Event | Triggered When |
|---|---|
item.created | A new item is created on any board |
item.updated | An existing item is modified (field values, status, assignment, etc.) |
item.deleted | An item is permanently deleted |
kpi.threshold_breached | A KPI value crosses its configured amber or red threshold |
action.created | A new corrective action is created |
action.updated | An action’s status, assignee, or due date changes |
action.escalated | An action is escalated (manually or automatically) |
checklist.completed | All items in a checklist are marked complete |
audit.completed | An audit is finalized and marked complete |
Payload Format
Each webhook delivery sends a JSON payload with the following structure:
{
"event": "item.created",
"timestamp": "2026-03-30T14:22:00.000Z",
"organizationId": "clx...",
"data": {
"id": "clx...",
"name": "New production deviation",
"boardId": "clx...",
"...": "event-specific fields"
}
}
The data object contains the full entity that triggered the event. Field names match the tRPC API response format.
Verifying Signatures
Every webhook delivery includes an X-ProBeya-Signature header containing an HMAC-SHA256 signature of the request body, computed using your webhook’s signing secret.
To verify a delivery in your handler:
const crypto = require("crypto");
function verifySignature(body, signature, secret) {
const expected = crypto
.createHmac("sha256", secret)
.update(body)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
Always use timing-safe comparison to prevent timing attacks when verifying signatures.
Webhook Lifecycle
Webhooks follow a defined lifecycle:
- Created — admin configures the URL and events; a signing secret is auto-generated.
- Active — the webhook receives event deliveries via HTTP POST.
- Disabled — after 10 consecutive delivery failures, the webhook is automatically disabled. It can also be manually disabled by an admin.
- Re-enabled — admin fixes the endpoint and re-enables the webhook. The failure counter resets to zero.
- Deleted — the webhook is permanently removed from the database.
Delivery Logs
Each webhook delivery is logged with:
| Field | Description |
|---|---|
| Event | The event type that triggered the delivery |
| Status Code | HTTP response code from your endpoint (e.g., 200, 500) |
| Response Time | How long your endpoint took to respond |
| Timestamp | When the delivery was sent |
| Success | Whether the delivery was accepted (2xx status code) |
View delivery logs by clicking on a webhook in the settings page and selecting the Deliveries tab.
Testing a Webhook
Click the Test button next to any webhook to send a synthetic test event to your endpoint. The test delivery uses the item.created event type with sample data. Check your endpoint’s response and the delivery log to confirm everything works.
Managing Webhooks
- Edit — click on a webhook to change its URL or subscribed events. The signing secret cannot be changed; delete and recreate to get a new secret.
- Disable — toggle the Enabled switch to pause deliveries without deleting the webhook.
- Delete — permanently remove a webhook and all its delivery logs. This action cannot be undone.
Best Practices
- Respond quickly — return a
200status within 5 seconds. Process the payload asynchronously if needed. - Use HTTPS — webhook URLs must use HTTPS to protect payload data in transit.
- Verify signatures — always validate the
X-ProBeya-Signatureheader before processing a delivery. - Handle retries — design your endpoint to be idempotent, since failed deliveries may be retried.
Was this page helpful?