Webhook Registration

Following section shows how to get the list of registered webhooks in Litium, as well as how to register a web hook using web APIs. Here we use Postman for web API calls and there're some coding examples included. 

Registering a webhook

Pre-requisites

1. For installing postman, please see this article.
2. You need a service account in Litium to get authorization to do a web api request. Setup one as described here >>.
3. import this package into Postman. There're 5 request samples in this package.
4. Create a environment variable called host and set the value to point to your Litium server domain name. More information here >>.

1.1 . Create token request

We need to configure the client_id and client_secrent to use Litium service account. Litium Service Account should exists in the Litium server. You need the credentials created in step 2 in pre-requisites above.

It should look similar to this : 

Access token will be saved into a variable and included in other requests.

1.2. Get all Webhook Filter

This query will return all webhook events that could be subscribe to. The "name" field will be used in the webhook registration in step #3.

1.3 Register a Webhook

Erp connector could subcribe to Order Confirm event by sending over this registration, 

{
	"Id": "erpConnector",
	"WebHookUri": "http://erpconnector.local/api/webhooks/incoming/litium",
	"Secret": "12345678901234567890123456789012",
	"Description": "Erp Connector Demo",
	"IsPaused": "false",
	"Filters": ["Litium.Connect.Erp.Events.OrderConfirmed"]
}

- Id : Unique Id to identify the connector.

- WebHookUrl: Call back url of Erp Connector. The Order infomation will be sent to this url when order was confirmed.

- Secrect: Secrect code to secure webhook message.

- Description : Short description about the webhook registration

- IsPaused: Setting for enable/disable the webhook registration.

- Filters: a list of events that this registration hooks into. In this case we're subscribe to OrderConfirmed event from Litium. A full list of supported events could be retrieved in step #2 above.

Please make sure WebHookSelfRegistrationCallbackHost needs to be accessible from server because during registration controller will ping the url in WebHookUrl. If this connector was run locally then we could using ngrok to tunnel the traffic from Litium Server to local environment.    

1.4. Get all Webhook Registration

This will return all registrations for this user.

1.5. Delete Webhook Registration

We could delete registrations for a given user by calling registrations controller with DELETE action. There're two methods to delete registrations :

Delete all registrations of current service account user : 

Delete registration by id : 

Registering a webhook in code

The code below is included in Erp demo sample, which could be downloaded here.  

2.1 Get Authentication token from Litium

In order to make a call to Litium API, we should generate the token first. Here is the sample code to make a call to Litium Connect and retrieve the token : 

 public async Task<ILitiumWebHookClient> CreateWebHookClient()
        {
            await GetAuthenticationAsync();

            _client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(_oAuthResponse.TokenType, _oAuthResponse.AccessToken);

            return new LitiumWebHookClient(_client);
        }

        private async Task GetAuthenticationAsync()
        {
            if (NeedToGetAuthentication())
            {
                await _authRequestSemaphore.WaitAsync();

                try
                {
                    if (NeedToGetAuthentication())
                    {
                        _logger.Info("Requesting new token.");
                        
                        var request = new GetAuthenticationRequest(LitiumSettings.ClientId, LitiumSettings.ClientSecret);
                        _oAuthResponse = await MakeRequestAsync<OAuthResponse>(request);
                    }
                }
                finally
                {
                    _authRequestSemaphore.Release();
                }
            }
        }
        

GetAuthenicationRequest.cs

internal class GetAuthenticationRequest : BaseRequest
    {
        private readonly string _clientId;
        private readonly string _clientSecret;

        /// <summary>
        /// Initializes an instance of <see cref="GetAuthenticationRequest"/> class.
        /// </summary>
        /// <param name="clientId"></param>
        /// <param name="clientSecret"></param>
        public GetAuthenticationRequest(string clientId, string clientSecret)
        {
            _clientId = clientId;
            _clientSecret = clientSecret;
        }

        /// <inheritdoc/>
        public override string GetEndpoint()
        {
            return "/Litium/oauth/token";
        }

        /// <inheritdoc/>
        public override HttpRequestMessage GetHttpRequestMessage()
        {
            return new HttpRequestMessage(HttpMethod.Post, GetEndpoint())
            {
                Content = new FormUrlEncodedContent(new Dictionary<string, string>
                    {
                        { "grant_type", "client_credentials" },
                        { "client_id", _clientId },
                        { "client_secret", _clientSecret },
                    })
            };
        }
    }

Up to this point it's similar to what we did in step 1.1 using Postman.

Then we could create a webhook like this:

 var args = new WebHook()
            {
                Id = "ErpDemo",
                WebHookUri = new System.Uri($"{LitiumSettings.CallbackHost}/api/webhooks/incoming/litium/"),
                Secret = LitiumSettings.Secret,
                Filters = new List<string>("Litium.Connect.Erp.Events.OrderConfirmed", "Litium.Connect.Erp.Events.ReadyToShip"),
                Description = "ERP Demo"
            };

and calling webhook registration client for registering:

await client.WebHookRegistrations_PostAsync("skip", args);

The detail implementation could be seen in LitiumWebhookService.cs of the Erp Demo application.