How to handle API callbacks in ASP.NET MVC (Helloworks API in my case)

Question

As per their documentation from link https://docs.helloworks.com/v3/reference#callbacks

"With the HelloWorks API you can use callbacks to be notified about certain events. Currently we support a callback to be registered when a step is started, the cancellation of a workflow, and the completion of a workflow.

The callback URL will be called according to the following:

curl -X POST https://your.domain.com/some/path
     -H "X-HelloWorks-Signature: {signature}"
     -H "Content-Type: application/json"
     -d "{payload}

I am not able to figure out how can I handle the callback in ASP.NET MVC 4.0. The callback returns data on JSON format. Once I receive the data, I can format it as per my need and can save to database. But how can I get the data in my controller? Guidance from experts on APIs are highly appreciated. Thanks in advance.

Answer 1

Peter your guidance worked. I appreciate that. It was straight forward, only the technical jargon are making it intimidating :). Below are the code that worked. I am still to secure it using signature.

[HttpPost]
    public ActionResult Callback()
    {
        string rawBody = GetDocumentContents(Request);
        dynamic eventObj = JsonConvert.DeserializeObject(rawBody);

        Test newTest = new Test();
        newTest.Response = "Bikram-1" + (string)eventObj.type;
        var test = db.Tests.Add(newTest);
        db.SaveChanges();

        return Content("Success!");
    }

    private string GetDocumentContents(HttpRequestBase Request)
    {
        string documentContents;
        using (Stream receiveStream = Request.InputStream)
        {
            using (StreamReader readStream = new StreamReader(receiveStream, Encoding.UTF8))
            {
                documentContents = readStream.ReadToEnd();
            }
        }
        return documentContents;
    }

Answer 2

I am not able to figure out how can I handle the callback in ASP.NET MVC 4.0.

You need to have an api controller that accepts POST requests. That api endpoint is then called by the HelloWorks api. The fancy word to describe this mechanism is a Webhook. A nice introduction can be found here.

The very basic would be a controller like

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http;

namespace MyWebAPI.Controllers
{
    public class WebHookController : ApiController
    {
        // POST: api/webhook
        public void Post([FromBody]string value)
        {
        }
    }
}

You will need to register the url https://yourwebsite.domain/api/webhook at the HelloWorks api so it knows where to send the data to.

You probably want to secure this endpoint so others cannot abuse this api. See the docs for some guidance.

For example, in your case you should check that a header named "X-HelloWorks-Signature" is send in the request to the endpoint. The value of that header is a hash that should match the value of a hash of the content you received. To calculate the hash code to match create a hash using the SHA-256 algorithm and base16-encode the result.

There is also documentation from Microsoft on how to create web apis