SSL Panel configuration and explanation

• SSL Order status explanation
• SSL Panel end users access
• Setting up SSL Email notifications
• Setting up SSL Webhook notifications

SSL Order status explanation

Question

What is the meaning of all SSL Panel statuses?

Answer

There are few statuses available in "Certificate history" block in the right side of an order in SSL Panel.

After order has been created then following statuses are possible:

• Open
• Requested
• Active
• Rejected
• Revoked
• Expired.

Please refer to table below describing what each status does mean.

Status	Description
Open	Order is created but does not sent to CA for review. You can change CSR and other information such as requester, company etc. If it is OV/EV certificate with .nl common name and Dutch company then prevalidation is performed. If it fails certificate stays in the status "Open" with marked arrow "Requested".
Requested	When request is sent to the Certification Authority certificate is moved to the status "Requested" with marked arrow "Requested". You can also check when it was requested. If the customer has requested Cancellation from this status first it stays in the same "Requested" status with marked "Cancel" arrow. That means we have sent the cancel request to the CA and now we are waiting when they will cancel certificate to get "Cancel" status from CA. We can't influence process: from Comodo, we will get webhook message once it is done. This status corresponds to the "REJ" (Rejected) status in Openprovider.
Active	When certificate is activated (we get status from CA) it is moved to the status "Active". For the "Cancellation" from "Active" status the same logic is applied as for cancellation from "Requested" status - we send cancel request to the CA and mark arrow "Cancel" on the workflow (in Openprovider it corresponds to "REJ" - Rejected status):
Rejected	Once we get from CA that certificate is canceled it is moved to the status "Rejected" (corresponds to the "FAI" Failed status in Openprovider). Order set to the "Closed" status and then actions are available:
Revoked	Once certificate is canceled in CA it is moved to the "Revoked" status ("FAI" - Failed, in Openprovider).
Expired	Once a certificate expires it is moved to the "Expired" status.

SSL Panel end users access

Question

How to provide access to SSL Panel to an end-user?

Answer

One can do so by generating and providing links including secret tokens. 

You can reduce the support load for SSL certificate operations, by allowing the SSL Panel to guide your customers through the issuing process. The SSL Panel‘s URL is brand neutral and there is no mention of Openprovider anywhere in the user interface.
Present yourself as an independent provider to your customers.

The SSL purchasing process has two parts:

• ordering in your billing solution ;
• issuing through the SSL Panel ;

Functionality for user

1. Edit contact data inside an open certificate ;
2. Request a certificate ;
3. Choose DV (domain validation) method ;
4. Change confirmation email address ;
5. Resend confirmation email ;

Functionality for reseller (hidden from user)

1. Cancel a certificate, so another one can be requested using the same order ;
2. Cancel order ;
3. Paid or billing operations such as Reissue or Renew ;
4. Chat with CA ;

Providing user access via API

1. Get a temporary token for a particular SSL certificate order in the SSL Panel via the method - createOtpToken ;
2. Use the token and the URL from the response, you can generate a final URL for end user access using this format:  https://sslpanel.io/auth-order-otp-token?token=<token from createOtpToken request> ;

Multi-language support for users

The SSL Panel interface currently supports languages: English, Russian, Spanish, Dutch, Ukrainian.

Setting up SSL Email notifications

We have recently introduced a few new features that let you set up email notifications directly from the SSL panel for the most important events that happen for SSL certificates.
Please find below step by step instructions on how to configure them.

Email notifications - supported events

For the beginning we will support events such as:

Ssl_panel.requested - triggered when new certificate is requested from CA

Ssl_panel.reissue_requested - triggered when a reissue process for a certificates starts

Ssl_panel.reissue_failed - triggered when for any reason a reissue failed to be completed

Note: this notification is triggered when a reissue fails due to the error message from CA or internal error while reissue is requested. 

Ssl_panel.renewal_failed - triggered when for any reason a renewal failed to be completed

Note: Note: this notification is triggered when a renewal fails due to the error message from CA or internal error while renewal is requested. 

Ssl_panel.validation_failed - triggered when a validation failed to be completed

Note: Notification is triggered when a validation fails to be completed by CA

Ssl_panel.ca_chat.new_message_from_ca - triggered when there is a new chat message from the CA
ssl_panel.expired - triggered when the certificate expired 
ssl_panel.will_expire_in_30_days - triggered 30 days before certificate expiration date 

ssl_panel.will_expire_in_5_days - triggered 5 days before certificate expiration date

Note: By default the platform triggers automatic renewal (if auto-renew option is active) 15 days before the expiry of the certificate. 

If the renew event is triggered successfully, this notification will NOT be sent as the certificate changes it status to "Requested". 

You can activate selected events or choose “ * “ to activate all of them at once.

We plan also to add events such as: SSL is expiring (triggered X days before expiry date), SSL Expired or SSL renewal started. They should be available shortly.

How to set up new email notifications

1. First, please log in to your SSL Panel through RCP (Go to RCP > SSL certificates > Orders overview and click on any of the SSL order from the list):

2. Once you reach SSL panel click on Settings:

3. In Settings tab please click on Add notification:

4. You will be presented with a few dropdown options. Choose notification type email, then the event type and provide an email address which should receive them.

Lastly hit the Save button and that’s it!
From now on you will start receiving notifications for the events you have chosen.

IMPORTANT:
It is not possible to modify the body of notifications.
We have prepared a default layout and content for all our Resellers, with a principle in mind that these emails should provide brief and concrete information on a particular event and certificate.
If you think we can improve them, please let us know!

Setting up SSL Webhook notifications

Question

Is that possible to get notifications about SSL Order status change?

Answer

Yes, that is possible by setting up a webhooks on customer's end.

Webhook terminology

An event is a certificate change, such as a certificate being requested, issued, or failing validation. Each change has a corresponding Delivery object. Webhook endpoints are URLs defined by users to which Openprovider sends deliveries. A single event may be sent to many webhook endpoints. Webhooks refers to the overall concept of sending notifications to webhook endpoints. Webhooks refers to the overall concept of sending notifications to webhook endpoints.

Use webhooks to be notified about events that happen with certificates in Openprovider. Some events, like pre-validation results or issuance of the certificate, are not the result of a direct API request, so it could be a problem to keep track of the current state of certificates. Webhooks solve these problems by letting you register a URL to which we will send notifications anytime an event happens with a certificate under your account. When an event occurs - for example, when a certificate is issued, Openprovider generates a Delivery object. This object contains all the relevant information about what just happened, including the type of event and the data associated with it. Openprovider then sends the Delivery object to any URLs in your account's webhooks settings via an HTTP POST request. You can find a full list of all event types below.

Configuring webhook settings

Webhooks are configured in the Webhook settings section in SSL Panel. Clicking Add endpoint reveals a form to add setting for new subscription.

To configure it you should specify:

• URL where to deliver events
• Event type to be sent
• Secret key that will be used to generate a delivery

You can configure as many subscriptions as you want.

Common webhook mistakes

The two most common mistakes with webhooks are providing the wrong URL in the dashboard or the webhook endpoint not returning a 2xx status code. To test against these cases there is an option to send a test ping to each endpoint. Pings can be sent manually to verify functionality.

Available events:

• ssl_panel.created - Occurs whenever a new certificate is created
• ssl_panel.pre_validation.failed - Occurs whenever a validation fails
• ssl_panel.pre_validation.successful- Occurs when all validations have succeeded
• ssl_panel.requested - Occurs whenever a certificate is requested at the CA
• ssl_panel.ca_chat.new_message_from_ca - Occurs whenever the CA has sent new message to the chat
• ssl_panel.issued - Occurs whenever the CA has issued the certificate
• ssl_panel.will_expire_in_30_days - Occurs 30 days before the certificate expires all events - *
• ssl_panel.reissue_failed - Occurs whenever a reissue fails to be processed
• ssl_panel.renew_failed - Occurs whenever renewal fails to be processed

Data format

A webhook will POST to the URL with all data available in the body.

POST /payload HTTP/1.1
 
Host: localhost:4567
User-Agent: Tribuo/1.0
Content-Type: application/json
Content-Length: 6615
Version: "0.0.1" // Version of delivery structure
Signature: signature // HMAC hex digest of the payload, using the hook's
secret as the key (if configured).
Delivery: b32f3ff1-d7a4-479e-b6ae-1857533caa39 //
UUID of this delivery (for ability to check it later or store it).
Entity-Id: 192356 //
Entity id in application (if specified, for example order id)
Event: ssl.created
  
{
  // Available metadata
  "metadata": {
    "version": "0.0.1",
    "signature": "signature",
    "delivery": "b32f3ff1-d7a4-479e-b6ae-1857533caa39",
    "event": "ssl.created",
    "entityId": 192356
  },
  "data": {
    // JSON payload from application.
    // Payloads can be completely different from application
to application. That logic must be aligned before usage
of this service.
  }
}

Structure: delivery details, status mapping

Rules for status mapping

Openprovider API status	status	certificate.status	certificate.operation
PAI	open	open	none
ACT	open	active	none
open	replaced	none
FAI	closed	rejected	none
closed	revoked	none
closed	open	none
EXP	closed	expired	none
REJ	open	requested	deletecancel
open	active, replaced	deletecancel
REQ	open	requested	request
open	requested	reissue
open	requested	renew

Events:

• ssl_panel.pre_validation.failed
• ssl_panel.pre_validation.successful

{
"metadata":
{
    "version":"1.0.0",
    "delivery":"18bb58bc-2731-4d12-adb7-ec1e4fcc0ac7",
    "event":"ssl_panel.created",
    "signature":"sha256=8aca68f56d115c765cf91c1f2d27a7ef7348b698f8eed80aa2a34056adfee690"
},
"data":
{
    "id": "3d8b6599-0794-4c92-b019-ee939395b42a",
     "status": "open",
     "certificate":
     {
        "id": "09a704cb-3598-4324-a56f-eaa792f72a23",
        "status": "open",
        "expireAt": null,
        "operation": "none",
        "commonName": "openprovider.nl",
        "activatedAt": null,
        "certificates":
        {
            "main": null,
            "root": null,
            "intermediate": null
        },
        "preValidationStatus": "failed",
        "preValidationResults":
        [
            {"name": "whois_validator", "status": "passed"},
            {"name": "kvk_validator", "status": "failed"},
            {"name": "phone_number_validator", "status": "passed"}
        ],
        "openproviderId": 123456
    }
}

Events:

• ssl_panel.created
• ssl_panel.requested
• ssl_panel.issued ssl_panel.will_expire_in_30_days

{
"metadata":
    {
    "version":"1.0.0",
    "delivery":"18bb58bc-2731-4d12-adb7-ec1e4fcc0ac7",
    "event":"ssl_panel.created",
    "signature":
"sha256=8aca68f56d115c765cf91c1f2d27a7ef7348b698f8eed80aa2a34056adfee690"
},
"data":
{
    "id": "38e792f4-90f4-4e37-93ac-0478d01f954c",
    "status": "open",
    "certificate":
    {
        "id": "2410c949-9600-46ac-9c53-62de72742859",
        "status": "open",
        "expireAt": null,
        "operation": "none",
        "commonName": "openprovider.nl",
        "activatedAt": null,
        "certificates":
        {
            "main": null,
            "root": null,
            "intermediate": null
        },
        "preValidationStatus": "passed"
    },
    "openproviderId": 123456
}
}

Events:

• ssl_panel.ca_chat.new_message_from_ca

{
"metadata":
    {
    "version":"1.0.0",
    "delivery":"18bb58bc-2731-4d12-adb7-ec1e4fcc0ac7",
    "event":"ssl_panel.created",
    "signature":
"sha256=8aca68f56d115c765cf91c1f2d27a7ef7348b698f8eed80aa2a34056adfee690"
},
"data":
{
    "date": "2017-12-08T10:51:40+0100",
    "message": "We try to get contact the organization via the public
number +111111111 but we do not get anyone on the line. Can you indicate
when we can reached the organization for the validation?",
    "orderId": "0111111-1640-41d4-9b69-71600031d266",
    "openproviderId": "111111"
}  
}

Receiving a webhook notification

Creating a webhook endpoint on your server is no different from creating any page on your website.
With PHP, you might create a new .php file on your server; with a framework like Laravel, you add a new route with the desired URL.

Webhook data is sent as JSON in the POST request body. The full delivery details are included and can be used directly, after parsing the JSON into an Delivery object.

<?php

$body = file_get_contents('php://input'); // get request body
$delivery = json_decode($body, true) // decode delivery as array

// handle event

Responding to a webhook

To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code. Any other information returned in the request headers or request body is ignored. All response codes outside this range will indicate to Openprovider that you did not receive the webhook.

If a webhook is not successfully received, Openprovider continues trying to send the webhook once an hour for up to 3 days.

Verifying deliveries

As an extra security measure, you can verify a delivery before acting upon it:

<?php

// PHP 7.0+

$body = file_get_contents('php://input');
// get request body$delivery = json_decode($body, true)
// decode delivery as array// get signature that has been generated by sender
[$algorithm, $senderHash] = explode('=', $_SERVER['HTTP_SIGNATURE']);
// generate our signature
$knownHash = hash_hmac($algorithm, $delivery['data'], 'secretPhrase');

// now we can check generated signature against ours
if (!hash_equals($knownHash, $senderHash)) {
    header('HTTP/1.0 403 Forbidden');

    echo 'You are forbidden!';
}

// handle event