Skip to content

Setting up the customer solution

Webhook request payload

When calling your customer solution, PIM makes a POST request with a json body according to the following specification:

1
2
3
4
ExternalBulkOperationWebhookPayload {
  operationName*        string
  productUniqueNames*   [string]
}

The fields of this body are used as such:

  • operationName is the unique system name of the external bulk operation, and is used to distinguish external bulk operations from one another when sharing a customer solution URL.
  • productUniqueNames is an array of the unique names of the products that were matched by the product catalogue filter when triggering the external bulk operation from the dashboard.

Using the PIM client Nuget package

For your convenience, we provide a PIM SDK client with model definitions for all webhook payloads, among other things, in the form of a C# Nuget package. We recommend using this Nuget package as it will be updated if the payload format for webhook changes. The external bulk operations webhook request payload is represented by ExternalBulkOperationWebhookPayload, which is also exposed in the PIM OpenAPI specification, such that additional clients for other languages can be generated at will.

Webhook request timeouts

By default, PIM waits up to 2500 milliseconds for a response when calling the customer solution endpoint. For this reason, it is not necessarily feasible to perform the entire bulk operation before sending a reponse. Customer solutions should instead store the information received in the webhook request, and asynchronously pick up the job for processing.

If no response is received within the timeout period, the external bulk operation is considered to have failed. If, for some reason, your systems cannot provide a response within 2,500 milliseconds, you can reconfigure the timeout up to a maximum of 10,000 milliseconds (10 seconds) via the tenant preference WebhookInvocationTimeout.

Accepted status codes

Within the external bulk operation timeout period, the customer solution must send a response with a status code between 200 and 299 to indicate that the webhook request has been received successfully. Due to the asynchronous nature of processing these external bulk operations, a status code of 202 would be appropriate in most situations.

All other status codes can be used to indicate a failure. When receiving an unsuccessful status code while triggering an external bulk operation, the status code is presented to the user triggering the operation, which can be useful for debugging why certain external bulk operations have failed.

It is also possible for the customer solution to provide a descriptive error message in the body when responding to the webhook request. The contents of this response body are being written to the PIM error log for debugging.