Fusion API Webhook Integration Guide

This document provides guidance for clients to integrate with our webhook system. By registering a webhook endpoint, clients can receive real-time notifications when all Events created for DataFiles posted to Venture Fusion API from your application.

Webhook Registration

To begin receiving webhook events, clients must share the following info about their webhook endpoint with us. The following fields are required:

  • webhookUrl: Webhook Endpoint Customer URL; Must be provided to us

  • customerId: Venture Fusion Application Customer Id (We will assign this value)

Webhook Payload Structure

When an event is triggered, our system will send a POST request to your registered webhookUrl with a JSON payload. Below is a sample payload

Example JSON payload

{

               "id": "7d556e5a-f10e-4821-9a5b-68baa15c4755",

               "entityId": "479b6ff9-3748-4a19-8a56-a0d880db231e",

               "source": "DataFiles",

               "specVersion": "1.0",

               "type": "DataFile_Processed",

               "subject": "DataFile_Processed",

               "time": "2024-03-01T19:56:55.3822829",

               "dataContentType": "application/json",

               "data": {

                              "EntityId": "479b6ff9-3748-4a19-8a56-a0d880db231e",

                              "SubjectHandle": "Optional Field",

                              "RecordHandle": "Required Field_Could be LetterID"

               },

               "eventTypeId": 2

}

Payload Field Descriptions

Data Object Field Description

Response Expectations

  • Your endpoint must return HTTP 200 OK.

  • Any other response or timeout will trigger a retry.

Error and Retry Mechanisms

  • Retry Mechanisms: Retry is in place for 24 hours.

  • Error Handling: Retry will continue for 24 hours, and if no success, then error is considered a full failure, at which point the events are caught and monitored as “Dead-Letter” storage containers.

  • Rate Limiting: There are no Rate Limits currently.

Client Application Response Time

When the client application eventually becomes available and processes the webhook successfully, it needs to respond with a 2xx HTTP status code within a specific timeout window. This timeout is often around 10 seconds, and failure to respond within this time will trigger further retries.

Webhook Provider's Retry Policy

  • Azure Event Grid implements an exponential backoff strategy. This means the delay between retries increases after each failed attempt.

  • For example, Event Grid uses a schedule like 10 seconds, 30 seconds, 1 minute, 5 minutes, 10 minutes, 30 minutes, 1 hour, 3 hours, 6 hours, and then every 12 hours up to 24 hours.

Maximum Delivery Attempts

The default is 30 attempts.

Event Time to Live (TTL)

The default TTL is 24 hours (1440 minutes).

Dead-Lettering

  • If an event cannot be delivered within the configured TTL or after the maximum number of attempts, it will be 'dead-lettered'.

  • For example, If you set the TTL to 30 minutes and the maximum delivery attempts to 5, Event Grid will stop retrying after 30 minutes or after 5 attempts, whichever comes first.

Optional Security Enhancement

To further enhance the security of webhook communications, we could offer the following optional features. Please let us know during registration if you would like to enable any of these:

  • Signature Verification
    We can include an HMAC signature in each webhook request. You can use this to verify the authenticity of the payload using a shared secret.

  • IP Whitelisting
    We can provide a list of static IP addresses from which webhook requests will originate, allowing you to restrict access to your endpoint.

  • Custom Authentication Headers
    If your system requires a specific authentication token or header format, we can include it in each request.