Configure Template group and Webhook

Integration Toolkit > Configure Template group and Webhook

Template group

Here we will discuss how to create a template group for your integration and add data fields to that template group to use when creating contracts to transfer data from your system. Usually, you have to do this template group creation while setting up the integration. You can refer Create a template type endpoint for this purpose.

Please follow the pseudocode below to understand the usage.

FUNCTION CreateTemplateGroup
	INPUT: API token, name, description(opitonal)
	OUTPUT: JSON repsonse of created template group or error

	BEGIN
	    SET token = API token  # Assuming you have API token from Oneflow

	    SET name = name  # Name for the template group. Ex: Demo Template
	    SET description = description  # Description for the template group
	    
	    
	    # ~ Begin the template group creation part ~
	    SET url = "https://api.oneflow.com/v1/template_types"

	    # Create the payload for the template group create request
	    SET payload = {
		"name": name,
		"description": description
	    }

	    # Add the necessary headers
	    SET headers = {
		"x-oneflow-api-token": token,
		"Content-Type": "application/json",
		"Accept": "application/json"
	    }

	    # Send the request to the template group create endpoint
	    TRY
		SEND POST request to url
		    WITH headers = headers
		    WITH data = payload

		RECEIVE response
		RETURN response.json  # Assuming successful execution
	    CATCH (Exception as error)
		RETURN error.json  # Return the error
	END

To add data fields to that template group, use Update template type data fields endpoint as follows.

FUNCTION AddDataFieldsToTemplateGroup
	INPUT: user (includes API token and email), template group ID, data fields
	OUTPUT: JSON repsonse of added data fields to the template group or error

	BEGIN
		SET email = "YOUR_USER_EMAIL"  # Assuming you have user with email
		SET token = "YOUR_API_TOKEN"  # Assuming you have user with token
	
		SET template_type_id = template group ID  # Get the template group ID from the CreateTemplateGroup response
	
		SET data_fields = data fields  # Data fields list to be added to the template group	    
	   
		Ex: data_fields = [
				{
					"custom_id": "demo_employee_name",
					"description": "The name of an employee.",
					"name": "Employee Name",
					"placeholder": "employee name",
					"value": "John Doe"
				},
				{
					"custom_id": "demo_employee_address",
					"name": "Employee address",
					"placeholder": "employee address"
				}
				]

	   
		# ~ Begin the adding of data fields to the template group ~
		SET url = "https://api.oneflow.com/v1/template_types/{template_type_id}/data_fields"

		# Create the payload for the data fields adding request
		SET payload = {
	    		"data_fields": data_fields
		}

		# Add the necessary headers
		SET headers = {
				"x-oneflow-api-token": token,
				"x-oneflow-user-email": email,
				"Content-Type": "application/json",
				"Accept": "application/json"
		}

		# Send the request to udpdate the template group with data fields endpoint
		TRY
			SEND PUT request to url
				WITH headers = headers
				WITH data = payload

			RECEIVE response
			RETURN response.json  # Assuming successful execution
		CATCH (Exception as error)
			RETURN error.json  # Return the error
	END

Webhook

Webhooks can be used to receive notifications from Oneflow for any changes that users make to contracts. To get notifications from contracts created using the template group (Ex: Demo Template) associated with your integration, you must create a webhook linked to that template group. This can be set up during the authentication process with Oneflow.

To create a webhook, you must provide a callback_url, template_group_id, and a sign_key. Through Oneflow, webhooks will deliver data such as contract_id, callback_id, and a list of events containing created_time, event_id, and type. By using the contract_id and event_id, you can retrieve additional information through the Get a Contract Event by ID Public API endpoint. You can find the supported webhook types in Oneflow in the documentation here.

To configure the events you want to receive notifications for, you can iterate through the events list and map them according to your application's naming conventions.

Once set up, Oneflow will trigger the webhook and send notifications directly to your system. To understand its usage, please follow the pseudocode below, which can be added to your system.

Ex: Create the webhook

FUNCTION CreateWebhook
	INPUT: API token, webhook URL, template group ID, sign key
	OUTPUT: JSON repsonse of created webhook details or error

	BEGIN
		SET token = API token  # Assuming you have API token from Oneflow

		SET callback_url = webhook URL  # URL, you have to give to recieve notifications
		SET template_group_id = template group ID  # Template group related to your integration
		SET sign_key = sign key  # key to verfiy webhooks from Oneflow

		
		# ~ Begin the webhook creation part ~
		SET url = "https://api.oneflow.com/v1/webhooks"

		# Create the payload for the webhook create request
		SET payload = {
			"callback_url": callback_url,
			"template_group_id": template_group_id
			"sign_key": sign_key
		}

		# Add the necessary headers
		SET headers = {
		    "x-oneflow-api-token": token,
		    "Content-Type": "application/json",
		    "Accept": "application/json"
		}

		# Send the request to the webhook create endpoint
		TRY
		    SEND POST request to url
		        WITH headers = headers
		        WITH data = payload

		    RECEIVE response
        
        # Retrieve authentication record
        oneflow_token <- API token
        authentication_record <- QUERY Database WHERE oneflow_token = oneflow_token

        IF authentication_record EXISTS THEN
            # Update existing record
            authentication_record.oneflow_sign_key <- sign key
            UPDATE Database WITH authentication_record
        END IF
		    RETURN response.json  # Assuming successful execution
		CATCH (Exception as error)
		    RETURN error.json  # Return the error
	END

Ex: Verify webhook signature when your integration receives an event to the above callback_url

FUNCTION verify_webhook_signature
    INPUT: webhook, sign_key
    BEGIN
        # Create webhook signature by combining callback_id and sign_key
        WEBHOOK_SIGNATURE = webhook.callback_id + sign_key

        # Formulate hash of webhook signature
        SET HASHED_SIGNATURE to COMPUTE_HASH_SHA1(WEBHOOK_SIGNATURE)

        # Retrieve the signature from the webhook
        SET EXPECTED_SIGNATURE TO webhook.signature

        # Compare the computed hash with the expected signature
        IF HASHED_SIGNATURE IS EQUAL TO EXPECTED_SIGNATURE
            RETURN TRUE  
        ELSE
            RETURN FALSE      
     END

Ex: Process the webhook received to the callback_url

FUNCTION process_webhook
    INPUT: body, account_id
    BEGIN
        # Forward webhook from Oneflow to external system and handle events
        SET webhook TO body
        SET external_system_account_id TO account_id
        
        # Step 4.1: Retrieve authentication data for the external system
        SET authentication TO QUERY Authentication WHERE external_system_account_id == external_system_account_id
        
        # Check if authentication exists for Oneflow
        IF authentication EXISTS
            RETURN "Event received!"  # Success message
        
        # Verify the webhook signature
        IF verify_webhook_signature(webhook, authentication.sign_key) IS FALSE
            RETURN "Event received!"

    END

To get specific events with webhook notifications, you can configure by iterating through events list and get the specific events.

FUNCTION filter_event
    INPUT: events
    BEGIN
        # Loop through each event in the list of events
        FOR each event IN events:
            # Extract the type of the current event
            SET event_type TO event['type']
            
            # Check if the event type is present in the STATUS_MAPPING
            IF event_type IS in STATUS_MAPPING:
                # If a match is found, return the mapped status
                RETURN STATUS_MAPPING[event_type]
        
        # If no matching event type is found, return NULL
        RETURN NULL
    END