Before you begin: This article is written for experienced TapOrders and Workflow users who are interested in using webhooks to push and pull customer information to and from TapClicks. For more information on TapOrders in general, please refer to this section of the knowledge base.
How To Create and Configure Webhooks in TapClicks
How to Capture Client, Order, and Line Item Data to Publish
How to Connect Your Webhooks to Tasks
Specifying Data Requirements for Partner Workflows in TapOrders & TapWorkflow
Sample JSON for “Create” Line Item
Introduction and Overview
The TapOrders and Workflow system from TapClicks includes the capability to push orders and line items to specific vendors for fulfillment. Webhooks allow for creating generic interfaces that publish data in standardized formats and push this data to any designated URL. This feature lets users build custom integrations, automating data transfer from their TapOrders and TapWorkflow system to any third-party fulfillment platform.
What is a Webhook?
A webhook, also known as a web callback or HTTP push API, is a tool that allows one application to send real-time data or messages to another application whenever a specific event occurs. Unlike traditional APIs, where you need to regularly check for updates, webhooks automatically send the information as soon as it’s available. Think of it like getting a notification on your phone - you don’t have to keep checking for new messages; the update comes to you immediately. In TapClicks, webhooks enable automated data exchange between TapClicks and other platforms, making your workflows more efficient and keeping your systems in sync.
Creating and Configuring Webhooks in TapClicks
Setting up webhooks can be challenging, but the TapClicks user interface simplifies the process. To ensure compatibility, it's crucial to have a good understanding of the destination platform's API, as the webhook configuration in TapClicks must match the destination application's setup.
The general steps for creating and configuring webhooks in TapClicks are as follows:
1] Create the webhook.
2] Enter the URL where the webhook will post/put data.
3] Configure the webhook to create, cancel, push, or edit objects.
4] Select the authentication model for the webhook.
5] Create and configure a task in TapWorkflow to trigger the webhook and push the desired package to the destination URL.
When the webhook is triggered, the payload, including line item details, is sent to the specified URL using the selected authentication mode. The destination platform processes the payload and sends an acknowledgment, which is recorded in the task's comments section. The task is marked as successful or failed based on the outcome. If the transaction fails, users can retry it using the "repush" action on the failed task.
For more detailed information about the webhook payload, including forms that collect order/product information in TapOrders, refer to Appendix B.
How to Create and Configure a Webhook
The following steps and screenshots guide you through creating and configuring webhooks in TapClicks:
1] Log in to TapClicks and on the left navigation menu, click Orders.
2] The TapOrders interface will open.
3] On the left, under Administration, click Integrations.
4] Click the Add Webhook button (+ icon) in the top right corner of the Webhook tile.
5] After clicking the tile, you will be asked to name the new webhook and choose a type for the webhook. When finished, click Save.
6] The webhook configuration screen will open.
7] Enter the URL where you want this webhook to publish in the Target URL textbox.
8] From the Method Type dropdown, select whether you want the webhook to Post (send) or Put (update) the data.
9] From the Event dropdown, select the event that triggers the webhook.
10] From the Entity Type dropdown, select what is supposed to be created by the webhook.
11] Finally, select an authentication method for this webhook.
| Note: There are three authentication methods: Basic, OAuth, and API Key. For Basic and API Key authentication, simply enter the required username and password on the configuration screen. If using OAuth 2.0, you'll need to provide the OAuth2 Client ID, Client Secret, and Token URL to request an authentication token from your authorization server. |
12] Once the configuration is complete, the webhook appears in the Integrations section with options to activate it using the Active/Inactive slider. The webhook must also be associated with tasks in TapOrders/Workflow for it to function properly.
How to Activate the Webhook
To successfully integrate a webhook with a third-party platform, the webhook must be properly configured and activated within the Integrations section of TapOrders. Once activated, associate it with the appropriate tasks in your workflow to ensure it triggers at the correct moments. The following steps will guide you through the process of linking your webhook for seamless data communication with external systems.
1] Log in to TapClicks and on the left navigation menu, click Orders.
2] The TapOrders interface will open.
3] On the left navigation menu, under Administration, click Integrations.
4] Navigate to the webhook section and locate your newly created webhook.
5] Activate the webhook by toggling the Active/Inactive slider.
6] Follow the steps below to link the webhook to the appropriate tasks in TapOrders/Workflow to ensure it triggers at the correct times.
The webhook should now be ready to communicate with a third-party platform.
How to Capture Client, Order, and Line Item Data to Publish
Capturing and configuring client, order, and line item data in TapOrders is essential for managing and transferring product information to third-party platforms. This process involves setting up product forms, organizing necessary data fields, and ensuring the information is correctly formatted for seamless integration. The following steps guide you through capturing and configuring this data within TapOrders.
1] Log in to TapClicks and on the left navigation menu, click Orders.
2] The TapOrders UI will open.
3] On the left navigation menu, under Administration, click Products.
4] Locate the product you want to configure and click View.
5] Click the arrow symbol (>) next to the Campaign Information section to expand and view its fields.
6] Note the information fields, such as campaign_name, campaign_start_date, and campaign_end_date, and how they are arranged on the form.
7] Recognize that the values captured by these fields will be included in the webhook payload and sent to the receiving API when the webhook is triggered.
9] Repeat this with the Ad and Targeting Information sections.
10] Once configured, tasks will be generated in TapWorkflow to trigger the webhook and submit the order or line item for fulfillment with the appropriate third-party API.
How to Connect Your Webhook to Tasks
After setting up your webhook, you can link it to specific tasks within your workflows in TapClicks. By associating tasks with webhook events, you control when these webhooks are triggered, allowing for seamless data transfer to third-party platforms. Follow the steps below to connect your webhooks to tasks in TapClicks:
1] Log in to TapClicks and on the left navigation menu, click Orders.
2] The TapOrders UI will open.
3] On the left navigation menu under Administration, click Tasks.
4] If you already have a task configured, locate the task you want to edit. Otherwise, create a new task by clicking Add New.
5] In the Vendor Name dropdown, select the webhook you want to activate. This webhook will be one that you added to the Integration list.
6] After setting up your task, navigate to the Administration section on the left nav and click Workflows.
7] Choose the Workflow you want to update with the new task. Otherwise, create a new workflow by clicking Add New.
8] Set the Routing Rule Action and Status that will trigger the webhook to fire.
9] Save your changes to finalize the task configuration.
The webhook is now connected to the task and will activate based on the conditions you’ve set.
How to Gather the Right Data for Partner Workflows
When using TapOrders and Workflow, you need to set up forms to collect important information about your clients, orders, and products. These forms help manage the order fulfillment process. Once you've set up the forms, the information they gather will be sent to a specific URL using webhooks.
Whether you're working with TapClicks or setting up the forms yourself, it's essential to know what data you need to collect so the forms can be created correctly. This data is everything you need to fulfill orders for your products.
Below are some basic examples of the kind of data you might need to capture. The examples might not cover everything since TapOrders & TapWorkflow is highly flexible is flexible and can be adjusted to fit your needs. If you're having TapClicks help with this, make sure you share all the details that are necessary for your fulfillment process.
NEW ADVERTISER (Client) – Add / Update
Below is an example of the type of client information needed to build forms and capture client information in TapOrders, which can then be sent to you, as a TapClicks partner, via a webhook.
| Product/Order Form | Product Form Field (UI) | Data Type |
| Client | Tap Client Account Number | string |
| Client | Tap Client Billing ID | integer |
| Client | Tap Client Address 1 | integer |
| Client | Tap Client Address 2 | string |
| Client | Tap Client City | string |
| Client | Tap Client State | string |
| Client | Tap Client Zip | string |
NEW LINE ITEM (Product) – Add / Update / Cancel
Here is an example of Line Item (Product) information presented in tabular form. This is the kind of information that is needed to build forms and capture Product information in TapOrders, which can then be sent to you, as a TapClicks partner, via a webhook.
| Product/Order Form | Product Form Field (UI) | Data Type | Notes |
|---|---|---|---|
| Client | Client Name | string | |
| Client | Client Account Number | integer | |
| Client | External Account Number | array of values | Retrieved from mapping values - could be more than 1 |
| Line Item | campaign_name | string | |
| Line Item | start_date | datetime | |
| Line Item | end_date | datetime | |
| Line Item | day_part | Integer (lookup) | |
| Line Item | custom_day_part_day | Integer (lookup) | |
| Line Item | custom_day_part_time | time | |
| Line Item | estimate_id | string | |
| Line Item | spot_play_goal | integer | |
| Line Item | impressions_goal | integer | |
| Line Item | flight_cpm | Decimal (currency) | |
| Line Item | Targeting_type_1 | Integer (lookup) | Lookup List |
| Line Item | Targeting_value_1 | Integer (lookup) | Lookup List |
| Line Item | Targeting_type_2 | Integer (lookup) | Lookup List |
| Line Item | Targeting_value_2 | Integer (lookup) | Lookup List |
| Line Item | Targeting_type_3 | Integer (lookup) | Lookup List |
| Line Item | Targeting_value_3 | Integer (lookup) | Lookup List |
| Line Item | Geo location targeting | json | Geo targeting json |