Set up manifest webhook (coming soon)

The manifest webhook feature has several purposes:

Real-time Updates: to receive immediate notifications about shipment activities or status changes, ensuring that the information is up-to-date.
Integration: to better integration with various services and APIs by providing a mechanism to push data and initiate workflows based on shipping events.
Error Handling: to notify systems about issues or failures in manifest processing, allowing for timely corrections.

The Manifests webhook is developed as an alternative to the Get Manifest Status endpoint. Instead of calling to retrieve the manifest status and details, you can set up the webhook to receive the manifest details when the manifest request has finished processing.

🚧
Important
The manifest webhook is only used if you are using the Manifest Shipments Async endpoint to manifest asynchronously.

To set up the manifest webhook connection in SAPIENT, follow the instructions as explained in the following procedure.

On the SAPIENT Home page, in the left navigation panel, select API > Webhooks. In the page that opens, select the Manifest Webhook tab.

In the WEBHOOK DETAILS block of the Tracking Webhook tab, enter the necessary information as described in the following table.

💡
Tip
In the following table, the mandatory fields are marked with an asterisk (*).

Element	Basic authentication	OAuth2 authentication
Authentication type*	From the dropdown menu, if applicable, select the Basic authentication type. Basic is a simple authentication type built into the HTTP protocol. It involves sending the user's credentials (username and password) in an encoded format (Base64) within an HTTP header.	From the dropdown menu, if applicable, select the OAuth2 authentication type. oAuth2 is a specific protocol used for authorisation that allows third-party applications to access the user's data without exposing their credentials.
Endpoint URL*	Enter your endpoint URL. This is the URL that we use to connect for identification purposes.	Enter your endpoint URL. This is the URL that we use to connect for identification purposes.
Username*	Enter your username to identify and authenticate the INTERSOFT payload.	❌ Not applicable
Password*	Enter the password for the username you entered to identify and authenticate the INTERSOFT payload.	❌ Not applicable
Token URL*	❌ Not applicable	Enter your token URL. This is an endpoint we use to connect and get the security token.
Client ID*	❌ Not applicable	Enter your client ID to identify and authenticate the INTERSOFT payload.
Secret*	❌ Not applicable	Enter your secret to identify and authenticate the INTERSOFT payload

After entering all the necessary details, select to check if the setup is configured correctly. Once the test has been completed, and the setup configuration is correct, the webhook is activated and the following success response is displayed:

If for some reason, the connectivity test fails, the following message is displayed:

After, turn on the Active toggle if you wany to activate the manifest webhook.

Activating tracking webhook — Activating manifest webhook

🚧
Important
The webhook only works if it is in theActive state. Any changes made to the webhook configuration deactivates it. Therefore, make sure the toggle is set to Active whenever the configuration is updated.

Select to confirm the setup completion.

The webhook payload will be sent for manifest requests with a status of both COMPLETE and FAILED.

If the manifestStatus = COMPLETE, the webhook payload will be the same as the Get Manifest Status endpoint detailed response.

Example payload

{
  "ManifestRequestId": "3a0c17c5-0ca4-455c-ac65-a20d95e656bc",
  "ManifestRequestStatus": "COMPLETE",
  "ManifestCount": 1,
    "Manifests": [
      {
        "CarrierCode": "RM",
        "CreatedDateUtc": "2024-06-17T10:36:20.072Z",
        "ManifestDate": "2024-06-17",
        "ManifestImage": "jVBERw0KGgoAAAANSUhEUgAA.....A4QAAAXcCAYAAAB6Q0CbAAAAAXNSR0IArs4",
        "ManifestNumber": "ISH2802532",
        "Service": "CRL1",
        "ShippingAccount": {
          "AccountAlias": "Account 1",
          "AccountName": "AB VideoGames",
          "AccountNumber": "0123456789",
          "ShippingAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        },
        "ShippingLocation": {
          "LocationAlias": "Main Warehouse",
          "LocationCountry": "GB",
          "LocationPostcode": "TW20 0HJ",
          "ShippingLocationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        },
        "TotalItems": 562,
        "TotalShipments": 562,
        "TotalWeight": 545.612,
        "WeightUnitOfMeasure": "KG"
      }
    ],
  }

If the manifestStatus = FAILED, the webhook payload will be the same as the Get Manifest Status endpoint FailedStatus response – that is, it will contain a FailureReason and error details.

Failed request example

 {
       "ManifestRequestId": "3a0c17c5-0ca4-455c-ac65-a20d95e656bc",  
 "ManifestRequestStatus": "FAILED",  
 "ManifestCount": 10,  
 "FailedReason": "Reason for failure",{  
 "Message": "Error message ",   
 "Errors": "list of errors",[  
       }
   }

🚧
Important
If the webhook call is not sent successfully, SAPIENT will retry sending the webhook at the following intervals:

5 mins

15 mins

60 mins

If the retry attempts are all unsuccessful, the webhook call will fail and SAPIENT will no longer send it again. In this case the Webhook will be suspended. For more information on how to handle the webhook suspension, refer to the Webhook suspension section.

See also