Use webhooks

Enabling webhooks and getting Secret String

All webhook management can be done via the Partner page.

1. Navigate to the Partner tab

2. Enter your webhook URL

3. Click Enable Integration

Note: The webhook URL can be changed at anytime. The secret string cannot be changed, if it is compromised, contact Certn support.

Secrets are set at the Partner level

Partner resellers will use the same webhook and secret across all accounts and sub-accounts

Request attempts

Our API sends updates as POST requests to your user-defined endpoints as they become available.

When receiving a 408, 500, 502, 503, or 504 status code, it retries up three additional times, waiting longer between each call. For any other status code over 399, the API backs off on first try.

Webhook signatures

For added security, you can opt to have Certn send you signed payloads. When enabled, our API adds a Certn-Signature header along with each request to your endpoints. This header allows you to confirm that the request came from us.

After this setup, Certn starts to sign each webhook it sends to the endpoint.

Preventing replay attacks

A replay attack is when an attacker intercepts a valid payload and its signature, then re-transmits them. To mitigate such attacks, Certn includes a timestamp in the Certn-Signature header. Because this timestamp is part of the signed payload, it is also verified by the signature, so an attacker cannot change the timestamp without invalidating the signature. If the signature is valid but the timestamp is too old, you can have your application reject the payload.

Use Network Time Protocol (NTP) to ensure that your server’s clock is accurate and synchronizes with the time on Certn’s servers.

Certn generates the timestamp and signature each time an event is sent to your endpoint. If Certn retries an event (e.g., your endpoint previously replied with a non-2xx status code), then a new signature and timestamp is generated for the new delivery attempt.

Signature verification

The Certn-Signature header included in each signed event contains a timestamp and one or more signatures. The timestamp is prefixed by t=, and each signature is prefixed by a scheme. Schemes start with v, followed by an integer. Currently, the only valid live signature scheme is v1.

Certn-Signature:
t=1609459200,
v1=09efe4234a3cd00e44c20bcc00ef1b4f9d3f33ea87a7f04bc0d87fc0ef0f04e8,
v1=b36793a72f8bd71c8a165bd4b5aefb9fe9f5ac272ccbc8971c82c8c89cade770

Newlines have been added for clarity, but a Certn-Signature header is on a single line.

Certn generates signatures using a hash-based message authentication code (HMAC) with SHA-256. To prevent downgrade attacks, you should ignore all schemes that are not v1.

It is possible to have multiple signatures with the same scheme-secret pair. This can happen when you roll (ie. expire) an endpoint’s secret from the Dashboard. The previous secret will remain active for 48 hours. During this time, your endpoint has multiple active secrets and Certn generates one signature for each secret.

You can verify a Certn signature using the following steps.

Step 1: Extract the timestamp and signatures from the header

Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair.

The value for the prefix t corresponds to the timestamp, and v1 corresponds to the signature (or signatures). You can discard all other elements.

Step 2: Prepare the signed_payload string

The signed_payload string is created by concatenating:

• The timestamp (as a string)

• The character .

• The actual JSON payload (i.e., the request body, as text)

• (The original binary string)

Note: Using JS Express, this may cause a problem (no access to the original string without adding middleware)

Step 3: Determine the expected signature

Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the signed_payload string as the message.

Step 4: Compare the signatures

Compare the signature (or signatures) in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.

To protect against timing attacks, use a constant-time string comparison to compare the expected signature to each of the received signatures.

Sample code

To verify an individual signature (after preparing the signed_payload and splitting the v1 prefix from the signature):

Python

def verify_signature(signature: str, payload: str, secret: str) -> bool:
    verify_sig = hmac.new(
        key=secret.encode("utf-8"),
        msg=payload.encode("utf-8"),
        digestmod=hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(verify_sig, signature)