If an error occurs during the execution of an Extension Hook API the API will return a 500 Internal Server Error response code with a JSON body that has details about the error. In order for the calling function to get that error message, your API must return a 500 Response Code with the same JSON body.

👍
Coding with C#?
Learn how to call Hook APIs with the C# Client Library that already implements this logic.

Example Scenario

Let's review a scenario with the Create Autoship Process Hook that demonstrates an error occurring during the execution of a Hook callback API. In this scenario, a user tries to create an Autoship with no items from the Corp Admin application.

👍
Need a visualization?
See this Hook Sequence Diagram that shows the call sequence of the CreateAutoship Process Hook.

When the /api/extension/hooks/Autoships.CreateAutoship endpoint is executed from a Client Web App it will fail the Directscale validation check that an Autoship must have at least one item. This will cause the /api/extension/hooks/Autoships.CreateAutoship endpoint to return a 500 response with a JSON body that includes details about the error. The Client Web Application must return a 500 response with the same JSON body in order for this error to return to the Corp Admin user as shown in Figure 1 below.

1692 — Figure 1: An image of the Add Autoship Page inside the Corp Admin Application Displaying a validation error originating from the CreateAutoship Hook API.

HTTP POST call to an external system for the Autoship.CreateAutoship Process Hook

The JSON body of this POST call contains 0 Items. "LineItems": [], and will cause a validation error.

curl --location --request POST 'https://acme.clientextension.directscale.com/api/recievingendpoint' \
--header 'X-DirectScale-User: jsmith' \
--header 'X-DirectScale-RequestName: Autoships.CreateAutoship' \
--header 'X-DirectScale-CallbackToken: 011420320705c882aa382c46115587ec70238c11b82c16ee504a7ef5a71796d57787e12cc25a' \
--header 'Authorization: Bearer mcwod!j9xn2fylqo%2692kd09$jdi1l' \
--header 'Content-Type: application/json' \
--data-raw '{
    "AutoshipInfo": {
        "AutoshipId": 0,
        "AssociateId": 2,
        "ShipAddress": {
            "Id": 0,
            "AddressLine1": "350 S. 400 W.",
            "AddressLine2": null,
            "AddressLine3": null,
            "City": "Lindon",
            "State": "UT",
            "PostalCode": "84042",
            "CountryCode": "us"
        },
        "StartDate": "2022-03-04T00:00:00",
        "Frequency": 2,
        "LastProcessDate": "0001-01-01T00:00:00",
        "NextProcessDate": "0001-01-01T00:00:00",
        "LastChargeAmount": 0,
        "Status": null,
        "ShipMethodId": 1,
        "PaymentMethodId": "_TESTCARD_f16134da-b965-e819-78fd-227865f388aa",
        "PaymentMerchantId": 99,
        "Custom": {
            "Field1": null,
            "Field2": null,
            "Field3": null,
            "Field4": null,
            "Field5": null
        },
        "AutoshipType": 0,
        "LineItems": [],
        "FrequencyString": null,
        "CurrencyCode": null
    }
}'

JSON Body returned with a 500 response code

{
    "DiscoRemoteException": {
        "ErrorId": "eb530146",
        "ErrorMessage": "Items are required (Error Id: eb530146 from Hook callback: Autoships.CreateAutoship)",
        "RemoteStackTrace": ["Hook callback: Autoships.CreateAutoship"],
        "InternalStackTrace": "   at Disco.AutoShip.AutoShipService.ValidateAutoShip(UpdateAutoShipInfo autoShip)\\r\\n   at Disco.AutoShip.AutoShipService.CreateAutoShip_Unhooked(UpdateAutoShipInfo autoShip)\\r\\n   at Disco.Extensions.Hooks.CallBack.AutoshipHooksCallbackService.CreateAutoship_Unhooked(CreateAutoshipHookRequest request)\\r\\n   at DiscoMVC.Controllers.Extension.GeneratedControllers.AutoshipHooksCallbackController.CreateAutoship(CreateAutoshipHookRequest request) in C:\\\\DiscoBase\\\\1.0.5122.0\\\\DiscoMVC\\\\Controllers\\\\Extension\\\\Generated\\\\Extension.Controllers\\\\AutoshipHooksCallbackController.cs:line 155"
    }
}