Delivering real-time updates to external systems through secure, customizable, and retry-capable HTTP callbacks.
Purpose
Webhooks allow external systems to receive real-time updates when relevant events occur inside facilioo. This page outlines the core concepts, key entities, and known limitations of the current webhook system.
Basic Concept
ER Diagram
Webhooks in facilioo are composed of several related entities working together to trigger and manage outgoing HTTP requests:
- WebhookRegistration: Defines the configuration for a webhook (target URL, events to subscribe to, and authorization).
- WebhookTargetAuthorization: Stores the credentials or authentication details to be used when sending webhook requests for a particular
WebhookRegistration. - WebhookEvent: Represents a domain event that can be subscribed to via a
WebhookRegistration. It consists of an entity name (asProcess,Unit, etc.) and a type (see further below). AWebhookEventis individually created for each event attached in the creation of aWebhookRegistration. - Webhook: An instance triggered by a
WebhookEvent, if the corresponding domain event happens. By being related to aWebhookEventthey are unique for eachWebhookRegistration. Furthermore, eachWebhookhas a state which can be one of the values further below. - WebhookAttempt: A record of each attempt to deliver a
Webhook, including retry logic and response handling.
WebhookEventType
WebhookEventTypeThe type of WebhookEvent describes the kind of domain model change that triggers the event:
| ID | Type | Description |
|---|---|---|
| 1 | Created | A new entity was created in the system. |
| 2 | Updated | An existing entity was updated. |
| 3 | Deleted | An entity was deleted. |
WebhookState
WebhookStateThe state of a Webhook represents the current delivery state of an individual Webhook:
| ID | State | Description |
|---|---|---|
| 1 | Created | Webhook has been created but not yet delivered. |
| 2 | Retrying | Delivery has failed and is scheduled to be retried. |
| 3 | Successful | Webhook was delivered successfully (2xx status code). |
| 4 | Failed | All retry attempts have failed; Webhook is considered failed. |
| 5 | Aborted | Webhook was manually marked as aborted and will not be retried. |
| 6 | Pending | Webhook is waiting for grouping or scheduling. |
| 7 | Resolved | Webhook issue has been manually resolved. |
Example Instance
Example instance of registration for multiple events with triggered domain events resulting in Webhook instances and multiple attempts.
Lifecycle
- Register: Create a
WebhookRegistrationto specify the target URL, which events to listen to, and authorization. - Trigger: When an event occurs, a
Webhookentity is created. - Execute: A
WebhookAttemptis scheduled and executed. If delivery fails, it is retried based on a predefined schedule. - Resolve: If delivery succeeds or is aborted/resolved manually, the Webhook is marked complete.
Authorization
WebhookTargetAuthorization supports the following:
- Basic Auth (username/password)
- (Future) Other types via
AuthorizationType
Retry Mechanism
WebhookAttempts implement exponential back off:
- 1st retry: 5 min
- 2nd retry: 15 min
- 3rd retry: 1 hour
- 4th retry: 6 hours
- 5th retry: 12 hours
- 6th retry: 24 hours
Max attempts: 7
Registration
Refer to the Webhook Registration Recipe to create, trigger, and consume webhooks.
Known Issues
- No validation: The system doesn't validate whether a target URL is reachable or if the entity name is valid.
- No deduplication: Multiple identical registrations can be created.
- No clean-up: Registrations with persistent delivery failures are not removed automatically.
- Event coverage incomplete: Some entities/events are not yet supported. These include:
AccountTenantPropertyEntranceInquiry
- No central overview: Users cannot currently view or manage webhook registrations and their attempts in the UI of the facilioo platform.
Recommendations
- Use
POST /api/webhook-registrations/searchand search bytargetUrlto find active registrations for particular endpoints. - Avoid long-living webhook registrations unless required. Consider implementing your own clean-up policy by tracking failed attempts.