Consuming Payloads Using Webhooks

Overview

An API (application programming interface) call sends and receives information between 2 servers. For an API call to work, you must first put in a request for that information. But another server can put in the initial request instead of you. If set up correctly, your application can receive HTTPS calls from an external server. This means that the Unqork server becomes the listener for this request. We refer to this type of call as a webhook.

What You'll Learn

In this article, you'll learn:

• About the differences between webhooks and APIs.

• How to use a webhook.

• About webhook security.

• How to configure a module for webhooks.

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 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:

• To pull data from an external service, you must put in a request for an external API call.

• A webhook pushes data from an external service to you. An event typically triggers the sending of the request.

This image shows a simple comparison of APIs and webhooks:

Examples of trigger events could be the submission of an application. When an end-user 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

Another great example of webhooks in action is DocuSign. After signing a contract, DocuSign can send a request to the URL you provide 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 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 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. But requests can also be in XML. 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, POST, PUT, PATCH, and DELETE requests. As a note, webhooks usually send POST 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. Sometimes an external service needs an XML 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 (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 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 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.

Adding the API Specification Snippet

To use webhooks, let's first set up a module. In that module, you'll drag and drop an API Specification snippet. Using this snippet will ensure you're using Unqork's best practices.

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

To create a module in your application:

1.

Select the Modules tab from the left sidebar menu.

2.

Click the + New Module button.

3.

In the left sidebar of Module Builder, click the Snippets button.

4.

Enter API Specification in the search bar.

5.

Drag and drop the API Specification snippet onto your canvas.

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. Avoid toggling the Act as Super-user when Server Side Executing setting to ON. This setting can weaken the security of your application.

1.

In the Module Builder, hover over the left menu bar.

2.

Click Settings.

3.

Set the Server Side Execution Only toggle to ON.

4.

Set the Customize RBAC for this Module toggle to ON.

5.

Set Allow Access to Anonymous Users toggle to ON.

6.

Select Write from the Anonymous role's Permission drop-down.

7.

Click Save Settings.

8.

Save your module.

Sharing the Postback Module URL

After you've set up your module to receive webhook requests, you'll provide your URL 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 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.