Webhooks

When to use webhooks

The most common use case of webhooks is to automate the communication between Cryptlex and third-party apps asynchronously. You might use webhooks to:

Email a license key to your customer after a successful purchase.
Email your customer when the license expires.
Renew subscription licenses when your customer makes the payment.
Get notified through email or chat apps like Slack when a user activates a trial or license.
Any other integration your business needs.

Creating a webhook

To create a webhook, go to the Developer -> Webhooks section in the admin portal and click the Add button. A webhook form with the following fields will pop up:

URL

The endpoint which will receive the HTTP POST payload.

Token

The token is a secret that will be used to sign the payload using the HMAC SHA-256 algorithm.

Events

The list of events which trigger the POST request.

Enabled

If unchecked, the webhook will be disabled and will not send a POST request on the defined events.

An account can have up to 100 webhooks.

Each event type has a specific payload format with relevant event information. The payload is JSON, encoded as UTF-8, and is signed with the HMAC SHA-256 algorithm; the signature is included in the webhook-signature header. HTTP header names are case-insensitive, so read the header without expecting a specific casing. A typical delivery has the following structure:

  POST /webhook-endpoint HTTP/1.1
Content-Type: application/json; charset=utf-8
Content-Length: 661
webhook-signature: Bb3jMWkC1DOqEv5fAOsqwkKH7r57w9o8fZ3Jg72lNk0=

{
  "id": "d9c7a3a2-4f5e-4a3b-9b2e-8f1a6c0d7e42",
  "event": "license.created",
  "data": {
    "key": "D08B53-C564F8-463EA5-F16A15-E35D6E-D2559B",
    ...
  },
  "triggeredAt": "2018-04-20T13:11:34.6926949Z"
}

id uniquely identifies the event for the webhook and does not change between delivery attempts, so use it as an idempotency key to discard an event you have already processed. triggeredAt is the time the event was triggered and also stays the same across retries, so a retried delivery carries the same body and signature as the original attempt.

Verifying the signature

Verify the signature on every delivery to make sure the request really came from Cryptlex. The signature is computed as:

signature = Base64(HMAC-SHA256(key: webhook token, message: raw request body))

Follow these rules, which cover the most common integration bugs:

Hash the raw request body exactly as received, before parsing it. Parsing the JSON and re-serializing it will not reproduce the original bytes, because key order and whitespace are not preserved. This is the single most common mistake.
Treat the body as UTF-8 bytes. The payload is not ASCII-escaped, so values with accented characters or emoji carry raw multi-byte UTF-8. Hash the bytes as received; do not decode them to a string in another encoding and re-encode.
Use a constant-time comparison to compare the computed signature with the header value, not string equality.
Read the webhook-signature header case-insensitively.

Node.js

Python

const crypto = require("crypto");

// rawBody must be the unparsed request body as a Buffer.
// In Express, use express.raw() or the verify callback of express.json()
// to capture it before any JSON parsing.
function verifyWebhookSignature(rawBody, signatureHeader, token) {
const expected = crypto
  .createHmac("sha256", token)
  .update(rawBody)
  .digest("base64");
const received = Buffer.from(signatureHeader ?? "");
return (
  received.length === Buffer.from(expected).length &&
  crypto.timingSafeEqual(received, Buffer.from(expected))
);
}

Testing a webhook

You can send a test delivery to your endpoint at any time using the Web API:

POST https://api.cryptlex.com/v3/webhooks/:id/test

If your account is in the EU region, use https://api.eu.cryptlex.com/v3 as the base URL instead.

The test sends a sample payload for an event of your choice (it defaults to the webhook's first subscribed event), signed exactly like a real delivery. The response returns your endpoint's response along with the exact body that was signed and the signature that was sent, so you can reproduce the signature computation while debugging.

Two properties of test deliveries are worth knowing:

They are not recorded as webhook event logs and never affect the webhook's health or suspension.
The sample payload carries representative but synthetic values, including non-ASCII characters, so an endpoint that verifies signatures incorrectly fails the test instead of passing it by accident.

Delivery and retries

Each delivery attempt times out after 15 seconds. A delivery fails on any non-2xx response, or when no response is received.
A failed event is retried up to 5 attempts in total, 5 minutes apart. An event that exhausts all attempts is marked failed.

Webhook event logs

Webhook event logs show information about POST requests that were made when the webhook was triggered. You can use webhook event logs to see the status code returned by your endpoint, when the request was sent and received, and the reason for any retry. You can also resend a delivery from its event log using the POST /v3/webhook-event-logs/:id/resend endpoint.

An event log has one of the following statuses: queued, pending, retrying, succeeded, failed, or cancelled. The cancelled status means the webhook was disabled or suspended at the time the event fired, so no delivery was attempted.

Webhook health

The status property reflects the operational state of a webhook:

A webhook starts as Healthy. A single failed attempt does not change the status; the event simply enters its retry cycle.
The status transitions to Unhealthy once an event has exhausted all of its retry attempts and been marked failed.
The status transitions from Unhealthy to Suspended when the 50 most recent completed events have all failed. When a webhook is suspended, Cryptlex emails your account's notification address.
While Suspended, no automatic delivery attempts are made, but events are still logged, so they can be resent later.
A successful delivery, including a manual resend, immediately restores the webhook status back to Healthy.