SSL/TLS Security

Shipwell's API endpoints are served over the HTTPS protocol with SSL (Secure Sockets Layer)/TLS (Transport Layer Security) certificates.

Note

SSL (Secure Sockets Layer) certificates still are commonly known under the SSL abbreviation, however modern browsers, most internet access, etc. is secured with TLS (Transport Layer Security). The abbreviation SSL is more common in usage when referencing TLS for historical reasons.

Certificates

The actual certificates for api.shipwell.com and Shipwell environments (i.e. sandbox-api.shipwell.com ) can change without notice.
Shipwell certificates automatically expire after 30 days to 1 year from the date/time of certificate issue (SSL certificates aka certs have a start or issue date, expiration dates, etc.) and are renewed and cycled in automated ways.
Shipwell does not consider changing or renewing a specific certificate as a breaking change and will not give notice (this is normal for the internet as systems, browsers, etc. automatically or put in place ways to verify or trust the certificate and root certificate authority ).
Instead of trusting our exact certificate instance, integrators should trust our root certificate authority (which will be trusted by most software and operating systems already).
We will make our best effort to notify customers if our root certificate changes, but it is possible that this can change without notice. We strive to use root certificate authorities that are by default trusted on systems and software platforms within the last 10 calendar years.

Recommendation

Instead of trusting our exact certificate instance, integrators should trust our root certificate authority (which will be trusted by most software and operating systems already). If your operating system or trust store needs manual updating, following the instructions on the page. Shipwell's root certificate authority for api.shipwell.com and Shipwell environments (i.e. sandbox-api.shipwell.com) is CN=ISRG Root X1 as of 2024-07-22.

Trusting Certificates

There may be rare cases where you need to download or export a certificate from a root certificate authority or certificate authority. Some cases include where the operating system may be an older system or version or where an environment is not up-to-date with certificate authorities trusted by browsers in the most recent version of the environment's operating system.

The following will help you download or export the certificate or certificate chain needed to then trust or install the certificate(s) into your environment.

SAP Specific Note

If you utilize SAP's ERP then you may need to import root certificates and trust certificates manually in the SAP certificate trust store. SAP's help, knowledgebase, support, and/or your SAP systems integrator will provide specific details on this for your SAP implementation if needed.

Exporting Root Certificate or Certificate Chain with Browsers

The video above is a walk-through of how to export a certificate chain or the root certificate authority certificate from your web browser using Google Chrome as an example (the steps will be similar for other browsers).

Exporting Root Certificate or Certificate Chain with OpenSSL

OpenSSL is a freely available and widely used program for interacting with SSL certificates. OpenSSL is well documented with many resources available on the internet.

For example, this command will display the entire certificate chain for the Shipwell sandbox-api.shipwell.com environment, which you may then manually extract and save:

Copy

Copied

openssl s_client -connect sandbox-api.shipwell.com:443 -servername sandbox-api.shipwell.com -showcerts

Note

Replace sandbox-api.shipwell.com with the environment prefix (i.e. replace sandbox-api with api in for the production api.shipwell.com environment) or domain (e.g. api.shipwell.com) in the openssl command above if you need to apply this command or process to other environments.

How to Install or Trust a Certificate

To install a certificate into your particular operating system, ask your systems administrator or search for instructions from a reputable source on the internet for "How to install or trust a root or CA certificate in linux/windows/macOS/unix/etc.?".

You will need the root certificate file.

For example, here are the steps for common server operating systems:

Trusting Webhooks

The process for establishing and validating that webhooks are sent by Shipwell is documented here.