Webhooks

Webhooks provide a powerful way to receive real-time notifications when specific events occur. Instead of requiring clients to poll for changes, a webhook allows the platform to proactively send event data to registered consumers as soon as an event is triggered, enabling near real-time reactions and integrations.

Subscription Management

Clients (consumers) can subscribe to specific event types such as employee.started or absence.registered. The Webhook Hub manages these subscriptions and ensures that each consumer only receives relevant events. Subscriptions, available event types, and configuration can be managed through the Webhooks API.

More information can be found in: API documentation for Webhooks.

Event Processing & Notification Delivery

When an event occurs, the Webhook Hub processes it and delivers a notification to all subscribed consumers. Each notification is sent as an HTTP POST request containing a structured JSON payload. The payload focuses on describing what changed, rather than including full or sensitive data, enabling efficient and decoupled integrations between producers and consumers.

Error Handling & Retry Strategy

Webhook delivery is designed to be resilient and tolerant to consumer-side issues. A delivery is considered successful as long as the receiving endpoint responds with any HTTP status code below 500. This means that both successful responses (2xx), redirects (3xx), and client-side errors (4xx) are treated as successfully delivered messages.

Returning a 4xx status code signals that the event has been received but cannot or should not be processed, and the Webhook Hub will not attempt to resend it. In contrast, responses with a 5xx status code or failed delivery attempts such as timeouts or connection errors are treated as transient failures.

In the case of failure, the Webhook Hub retries delivery every five minutes for up to 72 hours. Retry attempts continue until a non-5xx response is received or the retry window expires. If delivery remains unsuccessful, email notifications are sent to the configured contact addresses, with periodic reminders while retries are ongoing.

Consumer Best Practices

Consumers are expected to design their endpoints to support reliable and scalable webhook processing. Endpoints should respond quickly and avoid performing long-running operations synchronously. A common pattern is to accept the request, persist the event internally, and return a response immediately while processing happens asynchronously.

Webhook delivery follows an at-least-once model, meaning events may be delivered more than once. Consumers must therefore handle duplicate deliveries safely, typically by implementing idempotency based on event identifiers or timestamps.

It is important to return appropriate HTTP status codes. Responses below 500 should be used once the event has been safely received, even if downstream processing has not yet completed. Status codes in the 5xx range should only be used for temporary failures where a retry is expected.

Endpoints should be designed for high availability and should tolerate retry patterns, including bursts of repeated deliveries. Consumers should also avoid strict schema validation that breaks when new fields are added, and instead handle payload evolution gracefully.

Finally, consumers are responsible for securing their endpoints, validating incoming requests where applicable, and monitoring webhook processing to detect and resolve issues efficiently.

Configuring Webhook Subscription

To activate a webhook subscription, the client must provide the event types to subscribe to, a publicly accessible endpoint URL capable of receiving HTTP POST requests with JSON payloads, any required HTTP headers such as authentication, and one or more email addresses for delivery notifications.

Notes

This article describes the current Webhooks implementation in CatalystOne.

Webhook subscriptions connected to API 3.0 are managed through CatalystOne Technical Consulting. However, the underlying delivery model, including event processing, retry behavior, and error handling semantics, is the same as described in this document.

For questions related to API 3.0 webhook subscription management, please contact support@catalystone.com.