Webhook Registration

The following section shows how to get the list of registered webhooks in Litium, and how to register a webhook using web api:s. Here we use Postman for web api calls and there are some coding examples included. 

Registering a webhook

Pre-requisites

1. Click here, for more information on how to install postman.
2. A Litium service account is needed to get authorization to do a web API request. Please read more about how to setup an account here.
3. Import this package into Postman. There are 5 request samples in this package.
4. Create an environment variable called host and set the value to point to your Litium server domain name. Please read more about how to create one and set the value here.

1.1 . Create token request

The client_id and client_secrent must be configured to use Litium service account. Litium Service Account should exist in the Litium server. The credentials created in step 2 in the pre-requisites above are needed.

It should look similar to this : 

The 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 subscribed to. The "name" field will be used in the webhook registration in step #3.

1.3 Register a Webhook

Erp connector could subscribe 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 information will be sent to this URL when the order was confirmed.

- Secret: Secret code to secure webhook message.

- Description: Short description of the webhook registration

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

- Filters: A list of events that this registration hooks into. In this case, we subscribe to the 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 the server because during registration controller will ping the URL in WebHookUrl. If this connector was run locally then ngrok could be used to tunnel the traffic from Litium Server to the local environment.    

1.4. Get all Webhook Registration

This will return all registrations for this user.

1.5. Delete Webhook Registration

Registrations for a given user could be deleted by calling the registrations controller with DELETE action. There are 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 the Erp demo sample. Please find the download of the Erp sample code here.  

2.1 Get Authentication token from Litium

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 is similar to step 1.1 using Postman.

A webhook like this could be created:

 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 detailed implementation could be seen in LitiumWebhookService.cs of the Erp Demo application.