Webhooks

Your integration architect needs ProBeya to push real-time event notifications to your enterprise service bus, trigger a ServiceNow workflow when actions escalate during TIER meetings, and feed KPI breach alerts into your plant's SCADA alert system. Webhooks provide event-driven, push-based integration with cryptographic payload verification using HMAC-SHA256 signatures.

Webhook management requires the manage_settings permission, restricted to org_owner, tenant_admin, and site_admin roles.

Webhooks vs. API Keys vs. Integrations: Choosing the Right Pattern

Criterion	Webhooks (Push)	API Keys (Pull)	Integrations (Slack/Teams)
Direction	ProBeya pushes to your endpoint	Your system pulls from ProBeya API	ProBeya pushes formatted messages
Payload	Raw JSON with event envelope	Full API response per endpoint	Rich formatted messages (Block Kit / Adaptive Cards)
Authentication	HMAC-SHA256 signature verification	Bearer token in Authorization header	Platform webhook URL
Use case	Event-driven automation, ESB integration	Data retrieval, dashboards, batch sync	Team notifications, meeting alerts
Latency	Near real-time (seconds)	On-demand (polling interval)	Near real-time (seconds)
GxP audit	Delivery logs with HTTP status codes	Request logs with API key ID	Fire-and-forget (no delivery log)

Supported Events

ProBeya emits webhooks for 15 event types across the operational domain:

Event	Description	Pharma Use Case
item.created	New item added to a board	Trigger downstream work order in SAP PM
item.updated	Item fields modified	Sync status changes to MES
item.deleted	Item removed	Archive corresponding record in external system
item.status_changed	Item status column updated	Trigger escalation workflow in ServiceNow
kpi.value_entered	New KPI data point recorded	Feed OEE data to Historian
kpi.threshold_breached	KPI crosses warning/alert threshold	Trigger SCADA alert or Andon signal
action.created	New action item created	Create CAPA in TrackWise
action.updated	Action item modified	Sync update to quality management system
action.escalated	Action escalated to higher tier	Page the on-call manager via PagerDuty
action.completed	Action marked as complete	Close corresponding ticket in ServiceNow
comment.created	New comment on an item	Post update to project Slack channel
member.added	New member joined the organization	Trigger onboarding workflow in HR system
member.removed	Member removed from the organization	Trigger offboarding and access revocation
checklist.completed	Checklist fully completed	Log completion in batch record system
audit.completed	Audit checklist completed	Trigger deviation report if findings exist

Getting Started

1. Navigate to Settings > Webhooks.
2. Click Create Webhook.
3. Enter the endpoint URL (HTTPS required in production).
4. Select one or more event types to subscribe to.
5. Click Create. Copy the generated signing secret immediately -- it is shown once.

Payload Format

Every webhook delivery uses a standard envelope:

{
  "event": "item.created",
  "timestamp": "2026-03-30T12:00:00.000Z",
  "organizationId": "org_abc123",
  "data": {
    "id": "item_xyz789",
    "boardId": "board_def456",
    "title": "Deviation - Line 3 OOS Event",
    "status": "Not Started",
    "createdBy": "user_ghi012"
  }
}

Field	Type	Description
event	String	The event type that triggered this delivery
timestamp	ISO 8601	When the event occurred (UTC)
organizationId	String	The organization that owns this event (tenant isolation)
data	Object	Event-specific payload with entity details

Signature Verification

Each delivery includes two custom headers:

Header	Content	Purpose
X-ProBeya-Signature	sha256={hex digest}	HMAC-SHA256 of the request body using the webhook secret
X-ProBeya-Event	Event type string	The event type (e.g., item.created)

Verification Algorithm

expected = HMAC-SHA256(webhookSecret, rawRequestBody)
actual   = parseHeader("X-ProBeya-Signature").removePrefix("sha256=")
isValid  = timingSafeEqual(expected, actual)

Security

Always use a timing-safe comparison function when verifying HMAC signatures. Simple string equality (===) is vulnerable to timing attacks that can leak the expected signature byte-by-byte. Use crypto.timingSafeEqual() in Node.js or equivalent in your language.

Signing Secret Architecture

Property	Value
Entropy	256 bits (32 random bytes, 64 hex characters)
Generation	crypto.randomBytes(32) backed by OS CSPRNG
Storage	Stored in the database (not hashed -- needed for HMAC computation)
Visibility	Shown to the admin in the settings UI

Delivery Lifecycle & Retry Logic

State	Description	Trigger
Active	Webhook receives event deliveries	Default state after creation
Disabled (auto)	10 consecutive delivery failures	Non-2xx response or timeout 10 times in a row
Disabled (manual)	Admin toggled off	Manual action in settings UI
Re-enabled	Admin re-enables after fixing endpoint	Failure counter resets to zero
Deleted	Webhook and all delivery logs permanently removed	Admin clicks Delete

Failure Handling

• A delivery is considered failed if your endpoint returns a non-2xx HTTP status code or does not respond within 5 seconds.
• After 10 consecutive failures, the webhook is automatically disabled to prevent wasted resources.
• Re-enabling a webhook resets the failure counter to zero.
• Successful deliveries (2xx response) also reset the failure counter.

Delivery Log

Each webhook maintains a delivery log accessible from the settings UI:

Field	Description
Event	The event type that triggered the delivery
Status Code	HTTP response code from your endpoint
Response Body	First 1,000 characters of the response (for debugging)
Attempt	Delivery attempt number
Delivered At	Timestamp of the delivery attempt

Enterprise Integration Patterns

Pattern 1: Enterprise Service Bus (ESB)

ProBeya → Webhook → ESB (MuleSoft / IBM MQ) → SAP / MES / LIMS

Subscribe to all events. The ESB routes events to downstream systems based on the event field.

Pattern 2: Quality Event Pipeline

ProBeya → kpi.threshold_breached → AWS Lambda → TrackWise CAPA creation
ProBeya → action.escalated      → AWS Lambda → PagerDuty page
ProBeya → audit.completed       → AWS Lambda → Deviation report in Ennov

Pattern 3: Audit Trail Replication

ProBeya → all events → Webhook → Splunk / ELK / Datadog

Subscribe to all events and forward to your SIEM for centralized audit trail compliance (21 CFR Part 11.10(e)).

Configuration Reference

Setting	Description	Constraints
URL	The HTTPS endpoint receiving POST notifications	Must be a valid URL; HTTPS required in production
Events	Array of event types to subscribe to	At least one event required
Enabled	Toggle to pause deliveries without deleting	Does not affect delivery log retention
Secret	Auto-generated 256-bit HMAC signing secret	Generated at creation; cannot be changed

Permissions & Security

• Webhook management requires manage_settings permission (admin roles only).
• All webhook records are scoped to the current organization for multi-tenant isolation.
• Webhook payloads never contain cross-tenant data.
• All CRUD operations are logged to the audit trail.
• The signing secret is visible to admins in the settings UI.

warning

The webhook signing secret grants the ability to forge valid payloads if leaked. Treat it as a sensitive credential. Store it in your integration system's secret manager, not in source control or plaintext configuration files.

Testing

Use the Test button to send a synthetic webhook.test event to your endpoint. This verifies:

• The endpoint URL is reachable from ProBeya's servers.
• Your server correctly verifies the HMAC-SHA256 signature.
• Your endpoint responds with a 2xx status code within 5 seconds.

Recovery Procedures

Scenario	Resolution
Webhook auto-disabled after 10 failures	Fix the endpoint, then re-enable the webhook in settings. The failure counter resets.
Missed events during endpoint downtime	Query the delivery log to identify missed events. Use the API to pull the current state of affected entities.
Signing secret compromised	Delete the webhook and create a new one (new secret is generated). Update the secret in your integration system.
Endpoint receiving duplicate events	Implement idempotency on your server using the timestamp + event + data.id as a deduplication key.
All webhooks suddenly failing	Check if your IP allowlist or firewall is blocking ProBeya's outbound IPs. Verify your SSL certificate has not expired.

Best Practices

• Always validate the X-ProBeya-Signature header to prevent spoofed requests.
• Respond with a 2xx status code within 5 seconds to avoid timeout failures.
• Use a queuing service (SQS, RabbitMQ, Kafka) behind your endpoint to handle bursts gracefully.
• Subscribe only to the events you need to minimize unnecessary network traffic.
• Monitor the delivery log for recurring failures -- set up alerts for auto-disabled webhooks.
• For GxP compliance, retain webhook delivery logs as part of your audit trail evidence.

Related Features

• API Keys -- Pull-based programmatic access for external integrations.
• Connectors -- Pre-built bidirectional sync with pharma enterprise systems.
• Integrations -- Formatted Slack and Teams notifications.
• Audit Log -- Webhook creation, deletion, and delivery events are logged.