Skip to main content

​
Manage webhooks

​
What does this do for me?

A webhook pushes real-time event data from KeylessSSL to your own server so you do not need to poll the API for changes.

​
Before you begin

  • You need an owner, admin, or operator role.
  • Your endpoint must use HTTPS and be publicly reachable.

​
Register an endpoint

  1. Open Webhooks.
  2. Select Add webhook.
  3. Enter the URL of your endpoint.
  4. Select which events to receive:
    • domain.verified — a domain passed ownership verification.
    • cert.requested — certificate issuance was requested for a domain.
    • cert.issued — the provider finished issuing a certificate.
  5. Select Add.
KeylessSSL shows the signing secret exactly once. Copy it so your endpoint can verify incoming deliveries.

​
Verify a delivery

Each webhook POST includes these headers:
  • x-keylessssl-event — the event name, such as domain.verified.
  • x-keylessssl-timestamp — the timestamp included in the signature input.
  • x-keylessssl-signature — a versioned signature in the form v1=<hex digest>.
Read the request body before your framework parses or reformats its JSON. Join the timestamp header, a period (.), and the exact UTF-8 request body. Calculate an HMAC-SHA256 digest with the signing secret, encode it as lowercase hexadecimal, prefix it with v1=, and compare it with x-keylessssl-signature using a constant-time comparison. Reject a request when the timestamp or signature is missing or malformed. KeylessSSL does not prescribe a fixed replay tolerance, so choose a maximum age for your application and reject timestamps outside that window. After verification, parse the JSON. Current event data contains:
  • domain.verified — domainId and apex.
  • cert.requested — certificateId and apex.
  • cert.issued — certificateId and apex.

​
Send a test delivery

  1. Open Webhooks.
  2. Select Test next to the endpoint.
KeylessSSL sends one webhook.test event to your endpoint without retrying on failure. Failed non-test deliveries are stored for retry. The default limit is five delivery attempts.

​
Edit or remove an endpoint

  1. Open Webhooks.
  2. Select Edit to change the URL or events.
  3. Select Delete to stop all deliveries to that endpoint.