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.
Concept

ER Diagram
Webhooks in facilioo are composed of several related entities working together to trigger and manage outgoing HTTP requests:
Configuration Entities
- WebhookRegistration: Defines the configuration for a webhook (target URL, events to subscribe to, and authorization).
Nested Configuration Entities
- 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). AWebhookEvent
is individually created for each event attached in the creation of aWebhookRegistration
.
Runtime Entities
- Webhook: An instance triggered by a
WebhookEvent
, if the corresponding domain event happens. By being related to aWebhookEvent
they are unique for eachWebhookRegistration
. Furthermore, eachWebhook
has 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.
Expected Usage
This documentation may appear more detailed than necessary — that’s because it includes insights into facilioo’s internal webhook handling. In most cases, you only need to create a WebhookRegistration (Recipe). This will automatically create:
WebhookRegistration
,WebhookTargetAuthorization
,- and one
WebhookEvent
per subscribed event.All other resources (
Webhook
andWebhookAttempt
) are runtime artifacts created by facilioo to manage the webhook lifecycle. You typically won’t interact with them unless something goes wrong — for debugging.Use the additional endpoints to diagnose delivery issues — for example, if your system doesn’t seem to receive a webhook call. There is no direct endpoint for WebhookTargetAuthorization, as it’s managed entirely through WebhookRegistration.
Enums
WebhookEventType
WebhookEventType
The 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
WebhookState
The 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 a single, unauthorized WebhookRegistration
with multiple WebhookEvents
that are each triggered once and handled individually. The Webhook
itself has also a reference to the WebhookRegistration
that has been omitted in this diagram.
Lifecycle
- Register: Create a
WebhookRegistration
to specify the target URL, which events to listen to, and authorization. - Trigger: When an event occurs, a
Webhook
entity is created. - Execute: A
WebhookAttempt
is 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:
- 0: No Auth (public)
- 1: Basic Auth (username/password)
- 2: API Token (not supported yet)
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
Hands On
This is what's important, if you want to integrate facilioo's Webhooks into your system.
Refer to the Webhook Registration Recipe to create, trigger, and consume webhooks.
Altering a
WebhookRegistration
Currently, altering
targetAuthorization
orenabledEvents
of aWebhookRegistration
isn't supported yet! If you need to change the used authorization for yourtargetUrl
or if you want to create, update, or delete enabled events, you need to create a newWebhookRegistration
and delete the existing one.
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 are not yet supported. These include:
Account
Tenant
Property
Entrance
Inquiry
- No central overview: Clients cannot currently view or manage webhook registrations and their attempts in the UI of the facilioo platform.
- Account Role Restriction: Currently, only accounts of a party with the type
PropertyManagementCompany
are allowed to use this feature. - facilioo Platform (Web/App): Actions performed via the facilioo platform (web or app) might not be properly synced into the Webhook system, despite the targeted entity is supported in general (e.g., creating a
Document
in an existingProcess
triggers no Webhook, but creating aDocument
in an existingProperty
triggers a webhook, despite all three entities being supported in general in terms of webhooks).
Recommendations
- Use
POST /api/webhook-registrations/search
and search bytargetUrl
to find active registrations for particular endpoints. - Avoid long-living webhook registrations unless required. Consider implementing your own clean-up policy by tracking failed attempts.