Webhooks: General Information

A webhook helps you to integrate external applications that provide data in their own format and need to submit this data to MYOB Acumatica. For example, HubSpot collects data about email clicks and can export this data in a specific format to a particular URL. By using a webhook, you can configure MYOB Acumatica to process the data submitted to a particular URL and save the data in MYOB Acumatica.

Learning Objectives

In this chapter, you will learn how to do the following:

  • Create a webhook handler that will process the webhook requests from the external application
  • Register the webhook on the Webhooks (SM304000) form of MYOB Acumatica
  • Include the webhook handler and the registered webhook in a customization project

Applicable Scenarios

You configure the processing of webhooks in MYOB Acumatica if you need to implement an integration with an external application that provides data in its own format, and if this format is not compatible with the web services APIs of MYOB Acumatica.

Configuration of Webhooks

To configure webhooks, you perform the following general steps:

  1. You create a webhook handler that processes the requests from the external application.
  2. You register a webhook that is supported with the webhook handler on the Webhooks (SM304000) form of MYOB Acumatica.
  3. You copy the URL that is generated during the registration of the webhook handler, and then specify this URL in the external application so that it sends requests to this URL.
  4. You test the processing of the requests.
  5. Optional: You include the webhook implementation in a customization project.

Webhook Handler

A webhook handler is a custom class that processes the requests passed to a particular URL. This class must implement the PX.Api.Webhooks.IWebhookHandler interface.

Tip:
The PX.Api.Webhooks.IWebhookHandler interface is available in the PX.Api.Webhooks.Abstractions.dll assembly.

The IWebhookHandler interface has one method with the following signature.

Task HandleAsync(WebhookContext context, CancellationToken cancellation);
In the HandleAsync method, you perform the following general steps:
  1. You process authentication information in the request.
  2. You transform the data in the external format to the data that can be saved in MYOB Acumatica.
  3. You invoke graph methods that save the data in MYOB Acumatica.
Tip:
You can write unit tests for your webhook handler. In a test, you can override only the virtual properties and methods of Webhook* classes that are relevant to the test. For more information about unit tests, see Unit Test Framework Guide.

Registration of the Webhook

After you have created a webhook handler and placed the DLL of the class in the Bin folder of your MYOB Acumatica instance, you need to register the webhook handler on the Webhooks (SM304000) form. In the Webhook Name box, you enter the name of the webhook. In the Implementation Class box, you enter the name of the webhook handler that you have created.

After the new webhook is saved on the form, the URL box contains the URL that can be used by an external application to send data to MYOB Acumatica.

Tip:
Webhook requests are summed with other API requests in the MYOB Acumatica license restrictions.

Preparation of the External Application

For an external application to send requests to MYOB Acumatica, you need to prepare the external application by specifying in it the URL generated on the Webhooks (SM304000) form.

You also need to implement requests to MYOB Acumatica that satisfy the following requirements:
  • The request type must be POST or GET.
  • The body must contain only data that can be transferred with the HTTP protocol.
  • The body of the request must be no longer than the value specified by the webhook:maxrequestsize key of the web.config file of the MYOB Acumatica instance. By default, this value is 1 MB. You can change the default value by specifying a different value in the key of the web.config file.
Tip:
If an error occurs during the processing of a webhook, the error is returned in JSON format, no matter which Accept header is submitted in the request.

Request Log

On the Request History tab of the Webhooks (SM304000) form, you can remove requests from the log and check the statuses of the processing of requests. You can also specify the type and amount of requests to be stored in the log.

In the log, the system stores the request body as a string. If the system can determine the encoding of the request body, the system reads the body as a string in this encoding. (The system determines the encoding based on the charset parameter in the Content-Type header. If there is no charset parameter, the system tries to use the default encoding for the media type in Content-Type.)

Tip:
You can limit the length of the body of each request that is stored in the history by using the webhook:maxbodysizetolog key of the web.config file of the MYOB Acumatica instance. By default, the length is 10 KB. The system trims the part of the body that exceeds the specified length.

Webhooks in a Customization Project

If the webhook must be used in multiple MYOB Acumatica instances, you can include the webhook in a customization project and publish this project to the needed MYOB Acumatica instances. For details about working with customization projects, see Managing Customization Projects.

To include the webhook in a customization project, you need to include the following project items:
  • Webhook, which includes the webhook registered on the Webhooks (SM304000) form
  • File, which includes the DLL file with code of the webhook handler

For details about webhooks in customization projects, see Webhooks.