An event is a certificate change, such as a certificate being requested, issued, or failing validation. Each change has a corresponding
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.
Use webhooks to be notified about events that happen with certificates in Openprovider. Some events, like pre-validation result 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 your 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.
- 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 - *
A webhook will POST to the URL with all data available in the body.
POST /payload HTTP/
// Version of delivery structure
// HMAC hex digest of the payload, using the hook's secret as the key (if configured).
// UUID of this delivery (for ability to check it later or store it).
// Entity id in application (if specified, for example order id)
// Available metadata
// 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|
Event ssl_panel.pre_validation.failed, ssl_panel.pre_validation.successful
Events ssl_panel.created, ssl_panel.requested, ssl_panel.issued, ssl_panel.will_expire_in_30_days
Receiving a webhook notification
Creating a webhoook 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 would 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.
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 for any reason, Openprovider will continue trying to send the webhook once an hour for up to 3 days.
Using and API call, you can get all deliveries that were not successfully delivered.
As an extra security measure, you can verify a delivery before acting upon it:
You can extract hash algorithm by splitting it with = (for example, we will send signature similar to this: sha256=8aca68f56d115c765cf91c1f2d27a7ef7348b698f8eed80aa2a34056adfee690, like GitHub does).
Right now we will support only sha256.