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 be Content-Type = application/json headers. The HMAC authentication hash should be transmitted in the headers with the name Orchestro-Auth.

​

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": "d2ebc07c-81ed-4326-be39-64b9d73bea5a",
"base64body": " 
eyJtYW5pZmVzdElkIjogImI0ZTg5OWI1LWZlYjItNGMwMC05Zjg4LTI4MGU2ZjZiOTRiMSIsICJzaGlwbWVudERhdG UiOiAiMjAyNC0wNC0wMVQxMTowNzo1MiIsICJhY2NvdW50TnVtYmVyIjogIlNRREgyNDA1MDgwMSIsICJhY2Nv dW50VHlwZSI6ICJTSElQUEVSIiwgInBhcmNlbHMiOiBbeyJyZWZlcmVuY2VJZCI6IG51bGwsICJzaGlwRGF0ZSI6I CIyMDI0LTA0LTAxVDExOjA3OjUyIiwgInNlcnZpY2VUeXBlIjogIkdSRCIsICJwaWNrdXBUeXBlIjogIlBpY2t1cCIsICJ wYXJjZWxUeXBlIjogIlAiLCAic2hpcEZyb20iOiB7ImNvbXBhbnkiOiAiQ29tcGFueSBDIiwgIm5hbWUiOiAiVGVtdSIsI CJhZGRyZXNzMSI6ICI3NzcgQ2FzaW5vIENlbnRlciBEciIsICJhZGRyZXNzMiI6ICIiLCAiY2l0eSI6ICJIYW1tb25kIiwgI nN0YXRlIjogIklOIiwgInppcCI6ICI0NjMyMCIsICJjb3VudHJ5IjogIlVTQSIsICJwaG9uZSI6ICIiLCAiZW1haWwiOiAiIiw gImFkZHJlc3NUeXBlIjogIlIifSwgInNoaXBUbyI6IHsiY29tcGFueSI6ICIiLCAibmFtZSI6ICJQYWxhbml2ZWwgTSIsICJ hZGRyZXNzMSI6ICI4MDggSGlja3MgQXZlIiwgImFkZHJlc3MyIjogIiIsICJjaXR5IjogIkFzaHRvbiIsICJzdGF0ZSI6ICJJT CIsICJ6aXAiOiAiNjEwMDYiLCAiY291bnRyeSI6ICJVU0EiLCAicGhvbmUiOiAiIiwgImVtYWlsIjogIiIsICJhZGRyZXNzV HlwZSI6ICJCIn0sICJzZXJ2aWNlQXR0cmlidXRlcyI6IFtdLCAid2VpZ2h0IjogeyJ1bml0IjogIm96IiwgInZhbHVlIjogMT AuMH0sICJkaW1lbnNpb25zIjogeyJ1bml0IjogImluY2giLCAibGVuZ3RoIjogOC4wLCAid2lkdGgiOiAxMS4wLCAiaG VpZ2h0IjogMjUuMH0sICJ0cmFja2luZ0lkIjogIlBLMTQ0Rks5IiwgInBhcmNlbElkIjogIjY0NzU0ZjY4LWU0MGYtNGQ 4Yi1iNDg3LTkxYzU5MTU3Y2JiYSIsICJkZWxldGVkIjogZmFsc2UsICJvcmlnaW5Db2RlIjogIk9SQ0hFU1RSTyIsICJy ZWZlcmVuY2UxIjogbnVsbCwgInJlZmVyZW5jZTIiOiBudWxsLCAiZXhwZWN0ZWREYXRlIjogIjIwMjQtMDQtMDFU MTE6MDc6NTIifV0sICJjb3JyZWxhdGlvbklkIjogImVhMGRkMWY3LTQ3ZGYtNDQyZS1hZjkwLTM0YmJkMDdmNjQ 3YSIsICJuZXR3b3JrQ29kZSI6ICJPQ04iLCAibWFuaWZlc3RTb3VyY2UiOiAiTEFCRUwiLCAic2VydmljZUF0dHJpYn V0ZXMiOiBudWxsfQ== ",
"Auth": "7d66720034ecab1cccb5f89e0cd91c5bc8dcb2b6a41fc17bb03fdb46bb153b0f " }

​

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:

• C#

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.