Webhooks

Webhooks

Forbury provides webhook functionality for various events.

In order to use the webhook functionality, you must first be an existing Forbury Customer and be setup with API access.

Please see the Quick Start Guide for more on this.

Event types

Currently available webhook event types:

• ModelUpload - this is triggered when a user uploads a model to the Forbury Portal from within Excel using the Forbury Addin.
• ModelExtractionsCompleted - this is triggered when the models extraction process has finished generating PDFs and JPGs of your selected sheets and charts. Please see the Model Extractions wiki page for more information on this process.

Authentication options

Forbury currently provides two authentication methods.

1. OAuth2 workflow (Recommended) By providing Forbury with a ClientId and ClientSecret for authentication, you can control the permissions of your webhook endpoint with your existing authentication server.
2. Header Secret - Forbury will provide you with a secret, this secret can be added to your config file and ready for use with the ForburyAuthAttribute (see more in the example below).

Setup

To get started with webhooks, please first contact the Forbury development team ([email protected]) with the following information, based on your desired authentication option.

Forbury recommends using the OAuth2 workflow.

• OAuth2
  • ClientId (required) - A client ID for Forbury to use to be granted an access token, with the correct permissions for the webhook endpoint.
  • ClientSecret (required) - A client secret for Forbury to use to be granted an access token, with the correct permissions for the webhook endpoint.
  • Event type(s) (required) - One or more event type(s) to be notified on.
  • Endpoint(s) (required) - One or more endpoints for each event type requested (as HttpPost). This can also be one single endpoint with multiple event types, this will require your own object parsing.
• Header Secret
  • Event type(s) (required) - One or more event type(s) to be notified on.
  • Endpoint(s) (required) - One or more endpoints for each event type requested (as HttpPost). This can also be one single endpoint with multiple event types, this will require your own object parsing.

Please send the required information to [email protected] (or directly to a member of the Forbury Development team).

Retries

Failed webhooks will attempt to be resent up to 4 times.

Example usage

Once you are setup, you'll now need to create an endpoint to receive webhook requests from Forbury.

Please see the examples below based on your authentication option.

OAuth2 example (Recommended)

ForburyController.cs

using Forbury.Integrations.API.Models.Webhook;
using Forbury.Integrations.API.v1.Interfaces;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using System.Threading.Tasks;

namespace ForburyAPIDemo.Controllers
{
    [Authorize("forbury")]		// NOTE: Dependant on your auth provider
    [Route("forbury/webhook")]
    public class ForburyWebhookController : Controller
    {
        private readonly IForburyModelApiClient _forburyModelApiClient;

        public ForburyWebhookController(IForburyModelApiClient forburyModelApiClient)
        {
            _forburyModelApiClient = forburyModelApiClient;
        }

        [HttpPost("model")]
        public async Task ForburyModelUpload([FromBody] ModelUploadedEventDto modelUploadedEvent)
        {
            var model = await _forburyModelApiClient.GetModelById(modelUploadedEvent.ModelId);
        }
    }
}

Header Secret example

Once you have your secret(s) for the endpoints requested, you are ready to get started.

appsettings.json

"Forbury": {
  ...
  "Webhooks": [{
    "Endpoint": "model",		// Should match the endpoint template your are authorizing (as seen below)
    "Secret": "YOUR_WEBHOOK_SECRET",
  }]  
}

ForburyController.cs

using Forbury.Integrations.API.Attributes;
using Forbury.Integrations.API.Models.Webhook;
using Forbury.Integrations.API.v1.Interfaces;
using Microsoft.AspNetCore.Mvc;
using System.Threading.Tasks;

namespace ForburyAPIDemo.Controllers
{
    [Route("forbury/webhook")]
    public class ForburyWebhookController : Controller
    {
        private readonly IForburyModelApiClient _forburyModelApiClient;

        public ForburyWebhookController(IForburyModelApiClient forburyModelApiClient)
        {
            _forburyModelApiClient = forburyModelApiClient;
        }

        [HttpPostForburyWebhook("model")]           // This attribute will handle the validation of the secret header for you!
        public async Task ForburyModelUpload([FromBody] ModelUploadedEventDto modelUploadedEvent)
        {
            var model = await _forburyModelApiClient.GetModelById(modelUploadedEvent.ModelId);
        }
    }
}