Webhook

The webhook data exchange format is used in the Orchestro network for Orders/Manifest, Tracking and Errors. All manifests and events inbound to Orchestro are transmitted via webhooks. Data integrity and security is ensured by HMAC.

All outgoing webhook subscriptions are distributed via Amazon SNS. For the webhook endpoint, data is delivered without API authorization via POST to the URL supplied by the carrier. It is advised that carriers configure their endpoint with a portion of the URL randomly generated and treat the entire URL with the same level of confidentiality as a password.

Subscription: SNS requires an HTTPS endpoint to authorize a subscription on first initialization. Follow the steps below:

1. Initialize subscription with carrier specified endpoint.
2. SNS transmits a JSON object containing a subscribe URL string.
3. Authorize the subscription with the subscribe URL string by initiating a GET on the URL.
4. SNS Queue is now ready for use.

Here is a sample object for subscription in step 2

# Truncated for brevity 
{ 
  "Type": "SubscriptionConfirmation",   
  "Message": "You have chosen to subscribe to the topic XXX.\nTo confirm the subscription, visit the SubscribeURL included in this message.", 
  "SubscribeURL": "https://sns.us-east-1.amazonaws.com/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:us-east-1:505753670778&Token=2336412f37fb687f5d51e6e2425ba1f250507111f1dea5a045a6782d5e9fe52289cec3a0e544b8cab934a55a630b96a6a09437088abd095390988d4b77faf13af8d0e4e35852dacf5207dc25824dc2af9878ee8f15a2ea17204b7478e56a1d2dabed727783dee9034bfcddacbc562eeb71cbc88ddf5433aecb501c96e0084965", 
} 

Recommendation: A practical approach to capture the data involves dumping the content of the POST request into a logfile, then reading the subscription URL from this logfile. Since the subscription confirmation happens only once, this method provides a straightforward way to set up the subscription.

​

Standard Webhook Specification

This section outlines detailed information about the platform standards and formats for webhook submission.

​

Webhook Headers

Each webhook that is sent to Orchestro should possess the header in the below format:

  Content-Type: application/json

The HMAC authentication hash should be transmitted in the headers with the name Orchestro-Auth.

​

RSM Outgoing Webhook Authentications

To provide verification of authenticity of the origin, webhooks transmitted outbound from Orchestro are encapsulated and included as a base64 body field in the transmission. The same HMAC shared with the partner is used to sign the payload. Partners are encouraged to verify the HMAC signature before opening the payload.

{
  "correlationId": "******* correlationId *******",
  "base64body": "******* base64body *******",
  "Auth": "******* Auth *******"
}

​

Account Number and Carrier Code

The account number is part of the Orchestro system’s carrier profile. This value will be generated by Orchestro and provided via administration portal or during onboarding.

The Carrier code is a short, unique, and all-capital code that is specific to a carrier. Packages traveling through the system are tagged with the anticipated carriers using carrier codes. Fields for the origin and destination may be included.

​

Service Types and Service Attributes

See Network Codes and Network Service Attributes for the complete list of supported codes.

​

Dates

All dates should be sent in ISO 8601 format with time zone offset or Zulu time:

• 2024-02-20T23:38:22+07:00
• 2024-02-20T16:38:22Z

A timestamp with no offset is not acceptable.

​

HMAC Specification

Orchestro uses HMAC authentication to verify the integrity and authenticity of the transmitted data. To secure data with HMAC, the carrier should create a secret and share it with Orchestro in a secure manner. During transmission time, the HMAC should be computed on the final UTF-8 encoded and serialized payload.

For the HMAC computation use an HMAC library with the following parameters:

• SHA256
• Hex Encoded String

The addition of HMAC to an existing webhook integration is fairly simple due to ubiquitous support for HMAC signing in all major languages. The following code examples show how HMAC is added and implemented:

public static async Task<string> Publish(string endpoint, string json_payload, HttpClient httpclient)
{
    var request = new HttpRequestMessage() 
    {
        Method = HttpMethod.Post,
        RequestUri = new Uri(endpoint),
        Content = new StringContent(json_payload, Encoding.UTF8, "application/json"),
    };
    request.Content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
    request.Headers.Add("Orchestro-Auth", CalcHMAC(json_payload));
    var res = await httpclient.SendAsync(request);
    var retstring = await res.Content.ReadAsStringAsync();
    res.EnsureSuccessStatusCode();
    return retstring;
}
private static string CalcHMAC(string json_payload)
{
    // Secret loaded from secure storage
    var secret = "MY SHARED SECRET";
    var hash = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var byteval = hash.ComputeHash(Encoding.UTF8.GetBytes(json_payload));
    return BitConverter.ToString(byteval).Replace("-","").ToLower();
}

​

Webhook Endpoints

Upon signup, Orchestro will provide the carrier with webhook endpoints for Manifest and Event submissions. A status code 200 return indicates the webhook was successfully received. Any other return value indicates that the data transmission was incomplete and must be retried.