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.

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

Certificate Authority (CA) Certificates

Upload a CA Certificate

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

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

Request

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 looks like this:

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

Retrieve a CA Certificate

Request

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.

Delete CA Certificates

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

Reset CA Certificates

When uploading a CA certificate to the WhatsApp Business API client, if the certificate is invalid for some reason, the Webapp containers will fail to start on reboot as the API endpoint will be down. To recover from this situation, you need to drop the certs database table.

To drop the certs database table:

Stop the Webapp container:
```
docker stop your-webapp-container-id
```

Connect to MySQL via Docker in the command line:

docker exec -it your-mysql-container-id mysql -uroot -p

Enter your MySQL password when prompted (as per mysql.conf).
Check whether the certs table exists:
```
show tables in waweb;
```
Drop the certs table:
```
drop table waweb.certs;
```
Exit MySQL:
```
exit;
```
Restart the Webapp container:
```
docker restart your-webapp-container-id
```
Log into MySQL again using above steps to make sure the certs table now exists.

Webhook CA Certificates

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 {}