In this article:
- What is a webhook
- How to create a webhook
- Initial technical requirements
- How will the webhook receive data
What is a webhook?
A webhook is a way for an application to provide other applications with real-time information. A webhook delivers data to other applications as it happens, meaning you get data immediately from the Tradelens subscription, this is unlike typical APIs where you would need to poll for data very frequently to get it real-time.
If you are new to webhooks or just want to see how this works quickly without writing a new application, try an online webhook site like https://webhook.site/. It will create a new dynamic webhook URL for you and will display any events or data sent to it.
How to create a webhook?
Webhooks can be created with a variety of operational systems and web servers, in this section, we will give you step-by-step instructions to create webhooks with Linux and APACHE or Windows and NODE.JS.
Initial technical requirements
The webhook response
The webhook will receive arrays of events as the body of an HTTP POST request. As events arrive in your webhook application, first acknowledge that you have received the event with an HTTPS success code response (2nn) within 5 seconds (or the connection will be timed out) and then parse it to determine if action is required.
If the connection is timed out, TradeLens will save the payload and try again later. Unpublished payloads will be kept for 7 days, anything older than that will be deleted. The events are in JSON format. Depending on the programming language involved, several libraries are likely available for consuming this JSON data automatically, enabling you to walk through the data model to find what you need.
A webserver certificate
Your webhook server must present X.509 certificate information during the initial TLS security handshake. Your server's certificate must be signed by a well-known certificate authority (CA), perhaps via a certificate chain that includes one or more intermediate certificates, but it cannot be a self-signed certificate.
Also, as required by the TLS specification, your server must submit the entire certificate chain during the TLS handshake, including its own certificate, any intermediate certificates that your server may employ, and finally a root certificate that belongs to the list of well-known CA's.
A shared secret
A webhook can be configured with a shared secret, a key used to hash the event contents and store the results in the X-GTD-Signature header to be provided when publishing to your webhook. In your webhook application, you should use your shared secret to hash the event contents and ensure the resulting hash value matches what is found in the header. This allows you to verify the sender.
Guidelines for the shared secret:
- Your shared secret should be sufficiently long to be cryptographically secure.
- You should not use a predictable secret, like “passw0rd” or “sharedsecret1” since these can be easily brute-forced.
- It is recommended that you use a 30+ character string, created using a cryptographically secure random number generator.
- You should not use the same shared secret across multiple subscriptions.
- You should not store your webhook secret in “clear text” (unencrypted) anywhere in your system. You should store your secret in an encrypted format to prevent attackers from accessing your shared secrets.
- If your subscription is long-lived (you expect to continue receiving events for it over a period of months, this will usually be true for port, country, and org level subscriptions) you should change your shared secret regularly (at least once every 3 months).
If sharedSecret is included it will be used to calculate the Hash-based Message Authentication Code (or HMAC) signature. Our service currently supports the HmacSHA256 algorithm (see http://www.ietf.org/rfc/rfc2104.txt).
The HMAC signature is the product of a hash function applied to the body of a message along with the sharedSecret. When our microservice Shipping Information Pipeline (SIP) sends a subscriber an event, it stores the signature on the header named X-GTD-Signature. When the subscriber's server receives the event, it uses the same sharedSecret to compute the same HMAC. If the computed HMAC equals the value found in the header named X-GTD-Signature the request is authenticated. For the signatures to match, not only must the sharedSecret used at both ends of the transaction match, but the message body must also match exactly. Below is a Java sample to validate the X-GTD-Signature:
String xGTDSignature = "hashvaluefromheader";Mac hmac = Mac.getInstance("HmacSHA256");hmac.init(new SecretKeySpec("sharedSecretValue".getBytes( Charset.forName("UTF-8")), "HmacSHA256"));String calculatedSignature = Hex.encodeHexString(hmac.doFinal(event.getBytes(Charset.forName("UTF-8"))));logger.debug(className+"calculatedSignature: "+calculatedSignature);if(xGTDSignature.equals(calculatedSignature)){ // signed body matched}
Creating a webhook
Step-by-Step instructions in Linux and JS can be found below.
Linux – APACHE: You can find the step by step instructions in the video below:
JS (Any OS): A Git hub Sample can be found here: https://github.com/ibmgtd/sip-sample-webhook-node
You can find the step by step instructions in the video below:
You can also refer to this step by step article on How to create a webhook with Node.js
Testing your webhook
You can test your webhook by using the API call POST/api/v1/subscriptions/webhook/performTest, which can be found in the Event Subscription API section of the Swagger. This test simulates how the Platform publishes events to a webhook and can be used to debug problems with the webhook. A test event (the exact fields are provided below) is published to the url provided in the body of the request.
The API can be found at the following links in the Event Subscription API Swagger.
- https://platform-sandbox.tradelens.com/documentation/swagger/?urls.primaryName=Event%20Subscription%20API
- https://platform.tradelens.com/documentation/swagger/?urls.primaryName=Event%20Subscription%20API
How will the webhook receive data?
The webhook will receive arrays of events as the body of an HTTP POST request. The webhook must respond with an HTTP success code response (2nn) within 5 seconds or the connection will be timed out. If the connection is timed out, TradeLens will save the payload and try again later.
Unpublished payloads will be kept for 7 days, anything older than that will be deleted. If your service requires more than 5 seconds to process some events, it is recommended that the webhook responds to the HTTPS request with a success code to confirm it has received the event before it completes processing the event.
Your webhook URL must specify HTTPS. More specifically, it must support TLS 1.2. As an HTTPS / TLS server, your webhook server must present X.509 certificate information during the initial TLS security handshake.
Your server's certificate must be signed by a well-known certificate authority (CA), perhaps via a certificate chain that includes one or more intermediate certificates, but it cannot be a self-signed certificate.
Also, as required by the TLS specification, your server must submit the entire certificate chain during the TLS handshake, including its own certificate, any intermediate certificates that your server may employ, and finally a root certificate that belongs to the list of well-known CA's.
