WebHooks Documentation for Fonn Construction

Fonn Construction WebHooks mechanism for notifying third-party software about resources updates.

Getting started

WebHooks are based on HTTP Requests, so this mechanism calls a request that should be registered in the Organization Panel.

Notice that the WebHooks under continous development.
Some features may change in the future.

When user makes any change, the Fonn Construction system converts it into a WebHook message and notifies third-party service by calling registered WebHooks over HTTP.

General Communication with Fonn Construction system

While Webhooks notifies about changes by sending mostly basic data, third-party service may decide to query Fonn API for extended details.

1. User makes a change;
2. Core system processes the change and triggers webhook;
3. WebHook notifies an third-party about the change;
4. Third-party service can ask Fonn API Gateway for additional data (like a document URL);
5. API Gateway verifies the request and calls Core System for data;
6. Core API returns detailed data;
7. API Gateway forwards data to the third-party service.

Security

Fonn Construction system sends payloads only over the HTTPS protocol, due to security reasons. Also, there are implemented following mechanisms for verifying incoming requests.

• Api Key mechanism
• Payload Signing mechanism

We recommend implementing both mechanisms to pass highest security standards.

Registering a WebHook

To register a WebHook, your service needs to expose an endpoint over HTTPS protocol, which accepts POST request method with application/json Content-Type header.

Notice that the exposed endpoint should be available from a public network.

This endpoint should handle available payloads that you marked to support. If the endpoint received an unknown payload, we recommend returning a 400 Wrong Data error.

You can register a WebHook using two different ways.

Using Graphical User Interface (Fonn Construction Web App)

1. Contact with Fonn Construction support to enable WebHooks for your Organization
2. Go to Organization Panel
3. Expand Integrations tab
4. Go to WebHooks tab
5. Click add new WebHook

Using Fonn API

Guidelines available here: Fonn API - Getting Started

Available payloads for specific events

Checklists

• project_checklist_created - Checklist node created model
• project_checklist_updated - Checklist node updated model
• project_checklist_archived - Checklist node archived model
• project_checklist_comment_created - Checklist comment created model
• project_checklist_linked_item_added - Checklist related item added
• project_checklist_linked_item_removed - Checklist related item removed

Documents

• document_created - Document created model
• document_created_revision - Document revision created model
• document_updated - Document updated model
• document_removed - Document removed model
• document_removed_revision - Document revision removed model

Change Requests

• change_request_created - Change request created model

Issues

• issue_created - Issue created model
• issue_updated - Issue updated model

Issue Entries

• issue_entry_created - Issue Entry created model

Time Cards

• time_card_created - Time Card created model
• time_card_updated - Time Card updated model
• time_card_archived - Time Card archived model
• week_submitted - Week Submitted model
• week_approved - Week approved model
• week_rejected - Week rejected model

Organizations

Organizations

• organization_owned_user_assigned - Organization owned user assigned model

organization_owned_user_assigned

Payload of webhook sent after organization takes ownership of the user account.

Properties

Example

{
  "type": "organization_owned_user_assigned",
  "organizationId": "729cfcc1-2277-4e05-92c6-76302b32a83e",
  "data": {
    "userId": "12e84caa-fb17-46dd-b8b2-970ee563e606",
    "userExternalId": "adam-ext-123",
    "userName": "adam@fonn.com"
  }
}