Apaya is required to handle inbound notifications/Webhooks to ensure the uniformity of data between the Connector's and Apaya's environments.
Apaya will stipulate which Webhooks to handle from the Connector's platform. These will be included within the Connector Plugin. You may be required to advise after reviewing the Connector's documentation.
In this section, we will discuss how to configure webhook notifications for the connectors. In the previous section, we mentioned that upon creating the new plugin file that extends the IConnectorPlugin, missing methods need to be implemented. The HasWebhookSupport functionality indicates if the current version of your plugin currently supports the webhooks implementation.
To implement the webhook flow, we provided an interface IWebhookProcessor that will ensure the third-party uses a well-structured code that conforms to the Apaya standards. The latter interface will provide the following functionalities:
1. CanHandleWebhook: Validates that the processor that received a specific webhook event is recognizable by the processor and is able to perform the needed actions.
2. ValidateWebhookSchema: the 1st step that the processor will execute. This will guarantee that the webhook content received is valid and its format is what the processor expected it to be.
3. ValidateWebhookSignature: Validate that the incoming webhook originates from the correct connector.
4. WebhookTransactionIdsResponse: Return the unique transaction ID that is linked to the webhook being processed.
5. GetWebhookStatusResponse: Return the status of the webhook received.
Your custom processor should have a similar structure of the snippet below.
public class MyCustomProcessor: IWebhookProcessor {
public bool CanHandleWebhook (RawWebhook rawWebhook){
// Define the webhooks that my processor is able to handle
}
public void ValidateWebhookSchema (RawWebhook rawWebhook){
// Validate that the webhook has a valid schema
}
public WebhookTransactionIdsResponse GetTransactionIds (RawWebhook rawWebhook) {
// Return the unique id of my current webhook
}
public GetWebhookStatusResponse GetWebhookStatus (RawWebhook rawWebhook) {
// Return the status of my current webhook
}
public void ValidateWebhookSignature (RawWebhook rawWebhook, WebhookConfig webhookConfig) {
// Validate that the webhook being processed is received from a valid source
}
}
To facilitate the above implementation the libraries provide two main entities:
1. RawWebhook: This object is constructed by general properties that are common between the different webhooks that will be received by the Apaya system.
2. WebhookConfig: This object will contain configurations related to the webhook. One example would be a specific key-value entry that is used to validate the webhook signature.
The RawWebhook implementation defines an abstraction that allows the third party to capture the webhook information to a well-defined entity provided by the Apaya package. An important field is the SourceConnector that defines the source which is later used to find the correct webhook handler.
public class RawWebhook {
public RawWebhook (string sourceConnector)
{
SourceConnector = sourceConnector;
}
public JObject? Body { get; set; }
public string SourceConnector { get; set; }
public string? RawRequestContent { get; set; }
public string? RawQueryParamsStr { get; set; }
public Dictionary<string, string>? Headers { get; set; }
public Dictionary<string, string>? QueryParams { get; set; }
public T? TryCastBody<T>() where T : class => Body?.ToObject<T>();
}
The WebhookConfig is an entity that will contain configurations related to the webhooks that are defined by the third party Connector (such as a signature header) and setup with other required merchant level connector configurations. This entity will be used to dictate the webhook success/error flow along with other validation such as a hashed signature used by some connectors. See the ValidateWebhookSignature function within the Webhook processor class in the
Moreover, the library will also provide custom error classes to help with error tracing:
1. InvalidWebhookSchemaException: This exception will be associated with the webhook schema validation function provided by the interface. This exception shall be raised if the webhook being processed contains an unexpected format.
2. InvalidWebhookSignatureException: This exception will be associated with the webhook signature validation function provided by the interface. This exception shall be raised if the webhook is not sent from the expected origin.
Want to print your doc? This is not the way.
Try clicking the ⋯ next to your doc name or using a keyboard shortcut (
