Certificates

/v1/certificates

Use the certificates node to maintain your Certification Authority (CA) certificates for SSL configuration of both the WhatsApp Business API Client and Webhooks.

By default, the WhatsApp Business API uses a self-signed SSL certificate for HTTPS traffic. If you wish to use a CA cert, you need to upload the certificate to the WhatsApp Business API Client.

This document covers:

You must use the admin account to upload and delete all certificates or to retrieve a Webhook certificate.

Uploading a CA Certificate

Make sure that the uploaded certificate contains the following sections in one file and in the same order as displayed here:

  1. Private key
  2. Certificate
  3. One or more intermediate CA certificates — The WhatsApp Business API Client needs at least one intermediate CA certificate, otherwise, upload will fail.

To upload the certificate to WhatsApp Business API client, use the following API request, which contains the Content-Type of text/plain.

POST /v1/certificates/external
  Content-Type: text/plain
  Content-Length: content-size

certificate

If using cURL, the command will look like:

curl -X POST \
  https://your-webapp-hostname:your-webapp-port/v1/certificates/external \
  -H 'Authorization: Bearer your-auth-token' \
  -H 'Content-Type: text/plain' \
  --data-binary @your-path-to-certificate.pem 

If a certificate already exists, it will be overwritten. You must restart the web server, that is, all Webapp container instances, once the certificate is uploaded. You should be extremely cautious to only update the certificate with a valid (i.e., proper & correct) certificate. Otherwise, the web server will fail to restart (as the API endpoint will be down) and will require manual intervention to recover from the situation.

Response

null

Retrieving a CA Certificate

To retrieve the CA certificate stored in the WhatsApp Business API Client (i.e., direct download), use the following API request:

GET /v1/certificates/external/ca

Response

Content-Type: text/plain
Content-Length: content-size

certificate

If a CA certificate is not found, then a 404 response code is returned with no body.

Deleting CA Certificates

Deleting certificates is not supported. We could support this in the future if there is a use case we have overlooked.

Uploading Webhook CA Certificates

If the Webhook URL as configured in the application settings uses an internal CA cert, you need to upload it to the WhatsApp Business API Client so that it can be supported by the WhatsApp Business API. If you are using an externally known CA cert, you can safely skip this section.

You can generate a self-signed certificate in the PEM format by running:

openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out certificate.pem

The certificate file needs to be in the PEM format. If you have more than one certificate to upload, they should first be combined into a single file by concatenating them:

cat cert1.pem cert2.pem > bundle.pem

Request

POST /v1/certificates/webhooks/ca
Content-Type: text/plain
Content-Length: content-size

certificate

If you need to send the certificate over cURL, it should look like the following:

curl -X POST \
  https://your-webapp-hostname:your-webapp-port/v1/certificates/webhooks/ca \
  -H 'Authorization: Bearer your-auth-token' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: text/plain' \
  --data-binary @your-path-to-certificate.pem \
  -k

If a certificate already exists, it will be overwritten. All Coreapp nodes must be restarted after uploading the certificate for the changes to take effect.

Response

null or {}

Retrieving Webhook CA Certificates

Request

GET /v1/certificates/webhooks/ca

Response

Content-Type: text/plain
Content-Length: content-size

certificate

If no certificate is found, a 404 response code is returned with no body.

Deleting Webhook CA Certificates

Request

DELETE /v1/certificates/webhooks/ca

Response

null or {}