Consuming Payloads Using Webhooks

Overview

Unqork allows you to consume data payloads using webhooks, which retrieve real-time data integration from external systems into your Unqork application. A webhook A webhook is an automated HTTP request that's triggered by an event from a source system and sends a data payload to a new destination. allows one server to send data to another automatically when a specific event occurs. Unlike, a typical API APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. (application programming interface) call, where you must initiate the request for information, a webhook enables another server to make the request on your behalf. In this case, the Unqork server acts as the listener for the incoming request, allowing it to receive real-time data.

Webhooks vs. APIs

APIs and webhooks both move data from one place to another. While they're similar, they're not quite the same thing. When you send an API request, it travels to a series of URL A URL (uniform resource locator) is a unique identifier used to locate a resource on the internet. Also known as a web address. endpoints. But, the URL endpoint for a webhook is one of your choosing. In this case, the endpoint is your module's URL. So, this endpoint receives data from the external service or pushes data to you. On the basic level, the main difference between each type of call is that:

This image shows a simple comparison of APIs and webhooks A webhook is an automated HTTP request that's triggered by an event from a source system and sends a data payload to a new destination.:

A static image displaying difference betweeen API and Webhook

Examples of trigger Triggers activate another component when certain requirements are met. Trigger types include Concurrent, Post, and Error. Some components do not have the ability to trigger others. events could be the submission of an application. When an end-user End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product. submits an application, a webhook could send a request to your module's URL. Once received, you could configure your response as an email to your end-user.

Using Webhooks

An example of webhooks in action is DocuSign. After signing a contract, DocuSign can send a request to the URL A URL (uniform resource locator) is a unique identifier used to locate a resource on the internet. Also known as a web address. provided to DocuSign. You can then configure the response to be a notification email sent out to all signers. If you consider the alternative, doing the same action with an API APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. call would be inefficient. You'd have to keep sending requests to find out if all parties signed the document. That means either manually triggering the call or setting it up on a timer.

Using webhooks A webhook is an automated HTTP request that's triggered by an event from a source system and sends a data payload to a new destination. to send email notifications with DocuSign is just one example. You can also use webhooks to:

  • Synchronize data across many web applications.

  • Receive real-time data in your application.

Another example of using webhooks is the payment platform Stripe. It uses them to:

  • Send notifications for invoice payment failures.

  • Handle payments that need more action, such as authorization.

  • Track the active or inactive status of subscriptions.

  • Catch subscription changes and restrict access to products or services.

It's important to note that external services usually send webhook requests in JSON JSON (JavaScript Object Notation) is an open standard file and data interchange format. Unqork uses JSON for submission (record) data.. But requests can also be in XML Extensible Markup Language (XML) is markup language that lets you define and store data in a shareable way.. But how does that work when the Unqork platform is in JSON? Well, Unqork has an extra endpoint for webhooks called Execute via Proxy. Execute via Proxy lets your module receive any data format request. It also lets you receive the typical GET The HTTP GET method is used to request data from a server, typically retrieving information without modifying any resources., POST The HTTP POST method is used to send data to a server to create or update a resource, typically including the data in the body of the request., PUT The PUT method is an HTTP request method used in REST APIs to update an existing resource or create a new resource if it does not already exist., PATCH, and DELETE The Delete operation removes existing data records from a database, allowing users to eliminate outdated or unnecessary information within a system. requests. As a note, webhooks usually send POST The HTTP POST method is used to send data to a server to create or update a resource, typically including the data in the body of the request. requests. Where an issue may arise with XML format is when your module sends a response back to the external service. Responses from Unqork are always from data.resolved and always in JSON JSON (JavaScript Object Notation) is an open standard file and data interchange format. Unqork uses JSON for submission (record) data.. Sometimes an external service needs an XML Extensible Markup Language (XML) is markup language that lets you define and store data in a shareable way. response to work correctly. If this is the case, you won't be able to use that service. Does that mean there's no way to make your configuration work? No, you just can't use a webhook call. Instead, you'll need to set up your module with an API call.

Using Webhooks Securely

To use webhooks at Unqork, you'll need to change some of your module's security features. External services qualify as anonymous users because they're outside of Unqork. You'll need to set anonymous user RBAC RBAC (Role-Based Access Control) is a method to control system access for authorized users. The role in RBAC refers to the levels of access employees have to a network. (role-based access control) permissions to receive requests. Then you'll provide your external service with your module's URL endpoint. It's important to note sharing a URL A URL (uniform resource locator) is a unique identifier used to locate a resource on the internet. Also known as a web address. will make it publicly accessible. While discovering the URL and using it maliciously is unlikely, the risk does exist. If you don't want to take the risk, you can always use an API APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. call instead of a webhook.

How to Configure a Webhook Module

Let's look at the general steps you should take to use webhooks. When you set up a module, you'll enter a title that includes postback and a brief description of the module's purpose. That way, you're following best practices for webhook module configuration. For instance, you could enter postbackDocuSign as the ID for a module receiving DocuSign requests.

Creating an API module

To use webhooks, let's first set up an API module.

These instructions assume you have a workspace open, saved, and with a title.

To create an API module:

1. Click on the +Create New drop-down menu on the top right of your workspace.
2. From the drop-down, select Module.
3. In theModule Name field, use postback as a prefix, then enter a name for the module.
4. From the Module Type drop-down, select API .

A static image displaying the API Module configuration settings

5. Click the Create button.
6. Save your module.

Enabling Execute via Proxy

Now you'll access the Settings to configure your new module. You'll enable a few settings for the Execute via Proxy endpoint to work correctly. For one, you'll set the Anonymous role's permissions to Write. This setting lets you receive a request from your webhook service.

1. In the Module Builder, click the the (ellipsis) button.
2. Click ModuleSettings.
3. Click User Permissions.
4. Set Allow Access to Anonymous Users toggle to  (ON).
5. From the Anonymous role's Permission drop-down, select Write.

A static image displaying the User Permissions settings

6. Click Save & Close.
7. Save your module.

Sharing the Postback Module URL

After you've set up your module to receive webhook A webhook is an automated HTTP request that's triggered by an event from a source system and sends a data payload to a new destination. requests, you'll provide your URL A URL (uniform resource locator) is a unique identifier used to locate a resource on the internet. Also known as a web address. to the sender. Your URL looks something like this: https://{yourSubdomain}x.unqork.io/fbu/uapi/modules/{moduleId}/api/{path}. Here's a description of the undefined sections of this URL A URL (uniform resource locator) is a unique identifier used to locate a resource on the internet. Also known as a web address. example:

  • yourSubdomain: This is your postback module's environment.

  • moduleId: This is the module ID of your postback module.

  • path: This is optional, but you could use it to help specify the purpose of your postback module. For instance, you could enter docuSignEmail as the path to use this module to receive DocuSign requests.

Best Practices

  • Avoid toggling the Act as Super-user when Server Side Executing setting to  (ON), this setting can weaken the security of your application.

A static image displaying the Module settings

Resources

For more information, you can read about the APIs in our Documentation Hub.