Notes for Logic Apps around Webhook Actions

Azure Logic Apps (Logic Apps) is one of serverless services that Azure is offering. Of course the other one in Azure is Azure Functions (Functions). Logic Apps consists of many connectors and triggers to interconnect services outside Azure. A webhook connector is one of them which has unique characteristics to the others. In this post, we are briefly looking at some tips we should know when we use webhook actions in a Logic Apps workflow.

What is Webhook?

Webhook is basically an API. We register an API endpoint onto a certain service. When an event occurs on the service, it invokes the API endpoint and sends a payload to there through its request body. That’s how a webhook API works. Here are some picks:

• In order to use a webhook, we need to register it onto somewhere. The registration process is called Subscription. We may or may not explicitly perform the subscription process.
• During the subscription process, we store an endpoint URL, which is called Callback. After the subscription, an event occurs the callback is invoked.
• When we invoke the callback, we also send a data, called Payload through its request body. That means we always use the POST method rather than any other HTTP methods.
• If we don’t need the webhook any longer, we need to deregister it, which is called Unsubscription. This is performed either explicitly or implicitly.

Those four behaviours are the most distinctive ones on a webhook. Let’s take an example using Slack and GitHub. We have a simple scenario around those two services:

As a developer, I want to post a notification on a Slack channel when I push a commit to a GitHub repository so that other team members get notified of my code update.

• Get an endpoint URL from Slack to send a notification, which will be registered onto GitHub. This is the Subscription.
• The Slack endpoint URL is considered as Callback URL.
• Through the callback URL, a POST request is sent when a new push is made. The request contains the push commit details, which is the Payload.
• When we don’t need the notification, we simply delete the callback URL from the GitHub repository. This is the Unsubscription.

Does it make us have much more senses? Let’s apply them to Logic Apps.

Webhook Action on Logic Apps

A webhook action can be found like:

If we select it, we are given to enter those details. Here are the bits and pieces we are talking about in this post.

1. At the time of this writing, the picture only indicates two required fields – Subscribe - Method and Subscribe - URI. However, this is NOT true. Actually we have to fill in those FIVE fields at least.
   • Subscribe - Method
   • Subscribe - URI
   • Subscribe - Body
   • Unsubscribe - Method
   • Unsubscribe - URI
2. Both Subscribe - Method and Unsubscribe - Method only accept POST, not any other else. Like the picture above, if we select any method, GET for example, over POST, the Logic App will throw an error below. We can select any method, but this is NOT true. DO NOT get confused by the dropdown box.
   

3. Subscribe - Body is actually a de-facto required field as we need to pass a callback URL through its payload in JSON format. Therefore, the callback URL MUST be sent using the WDL (Workflow Definition Language) function, @{listCallbackUrl()} via the request body.

4. Both Logic App endpoint URL and the callback URL from the webhook action requires a SAS token, which is automatically generated. This SAS token is used for authentication. Therefore, there is no need to have another Authorization header. If we put the Authorization header by accident, the DirectApiAuthorizationRequired error will occur.
   

5. When a Logic App meets the webhook action within its workflow, it subscribes the subscription endpoint and waits for the callback sending a payload until it is called. The maximum waiting period is 90 days. The callback only expects the POST request.

6. When the callback sends a payload, the payload is considered as a response of the webhook action. Let’s have an example like below. The Logic App subscribe a Function endpoint. The Function sends a request back to Logic App through the callback URL, with a payload. Initial request body coming from Logic App has a productId property but the callback request body from Function changes it to objectId. As a result, the webhook action receives the new payload containing the objectId property.
   [code lang=csharp]
   dynamic data = await req.Content.ReadAsAsync();
   var serialised = JsonConvert.SerializeObject((object)data);
   using (var client = new HttpClient())
   {
   var payload = JsonConvert.SerializeObject(new { objectId = (int) data.productId });
   var content = new StringContent(payload);
   await client.PostAsync((string) data.callbackUrl, content);
   }
   return req.CreateResponse(HttpStatusCode.OK, serialised);
   [/code]

7. Regardless of the callback request that is successful or not, whenever the callback is invoked and captured by Logic App, its payload always becomes the response message of the webhook action.

8. Only after the callback response is captured by Logic App, the subsequent actions are triggered. If those following actions use the webhook’s response message, it will be the payload from the callback as described earlier.

9. Unsubscription is only executed when the Logic App run is cancelled or 90 days timeout occurs. It works as like a garbage collector.

10. Unsubscription doesn’t have to fire a callback.

So far, we have briefly taken a look at the webhook action of Logic App. Documentation around this still needs more improvements so it is worth noting those characteristics when using Logic Apps. By doing so, we will be able to reduce number of trial-and-error efforts.