Webhooks

📘

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

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 (as Process, Unit, etc.) and a type (see further below). A WebhookEvent is individually created for each event attached in the creation of a WebhookRegistration.

Runtime Entities

• Webhook: An instance triggered by a WebhookEvent, if the corresponding domain event happens. By being related to a WebhookEvent they are unique for each WebhookRegistration. Furthermore, each Webhook 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 and WebhookAttempt) 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

The type of WebhookEvent describes the kind of domain model change that triggers the event:

WebhookState

The state of a Webhook represents the current delivery state of an individual Webhook:

Example Instance

---

Lifecycle

1. Register: Create a WebhookRegistration to specify the target URL and authorization, as well as which events to listen to.
2. Trigger: When the specified event occurs inside the facilioo system, a Webhook entity is created.
3. Execute: The delivery of the Webhook is scheduled and executed by an instance of WebhookAttempt. If delivery fails, it is retried based on a predefined schedule.
4. 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 (attaches a Bearer token to the request header in the format Authorization: Bearer <token> issued by the facilioo platform)

---

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 or enabledEvents of a WebhookRegistration isn't supported yet! If you need to change the used authorization for your targetUrl or if you want to create, update, or delete enabled events, you need to create a new WebhookRegistration 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 existing Process triggers no Webhook, but creating a Document in an existing Property triggers a webhook, despite all three entities being supported in general in terms of webhooks).

---

Recommendations

• Use POST /api/webhook-registrations/search and search by targetUrl 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.