4.2.1 Integrations — Webhooks & Automation — Outbound Webhooks — Events and Payloads

Outbound Webhooks allow Praisma Hub to notify external systems about events in near real time. Webhooks provide a push-based integration model that enables automation, synchronization, and event-driven architectures without polling.

Event Model

Each webhook delivery corresponds to a discrete event emitted by the platform. Events are immutable and reference the originating entity and action.

Event attributes:

Event type identifier

Entity reference and action

Timestamp

Payload version

Example event emission:

event(new WebhookEvent('content.published', $payload));

Payload Structure

Webhook payloads follow a consistent JSON structure to simplify consumer implementations.

Typical payload:

{ "event": "content.published", "timestamp": "2025-01-10T12:00:00Z", "data": { "id": "uuid", "type": "article" } }

Payload versions are explicit to support backward compatibility.

Delivery Behavior

Webhook deliveries are asynchronous and non-blocking. Emission does not depend on the availability of the receiving endpoint.

Delivery characteristics:

At-least-once delivery

Retry on transient failure

Ordered per endpoint where applicable

Retry Strategy

Failed deliveries are retried using exponential backoff. Permanent failures transition the webhook to a failed state without data loss.

Example retry handling:

if ($attempts > $maxAttempts) { $delivery->markFailed(); }

Endpoint Configuration

Endpoints are configured per tenant with explicit event subscriptions.

Configuration options:

Endpoint URL

Subscribed event types

Secret for signature verification

Security and Verification

Each webhook request is signed to allow recipients to verify authenticity and integrity.

Example signature verification:

hash_hmac('sha256', $payload, $secret);

Requests are sent over HTTPS only.

Monitoring and Diagnostics

Delivery attempts, failures, and response codes are logged. Diagnostics are available to authorized users for troubleshooting.

Security and Isolation

Webhook emissions are tenant-scoped. Payloads include only data relevant to the subscribing tenant. Secrets are stored encrypted and never exposed in logs.