Use webhooks

This page is being updated. If you have questions, contact our support team.
​Webhooks​
 are custom callbacks in the form of HTTP POST​
 requests. Once configured, our API can provide real-time JSON-formatted​
 updates to your custom URL.
For this, you'll need setup your webhook URL in your team settings.
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.
First, generate a webhook secret in your team settings.
Secrets are team-specific
Generate a secret for each team that uses your API.
When verifying the signatures of calls against multiple teams, use theCertn-Team-ID header to know which secret to use.
​
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.
1
Certn-Signature:
2
t=1609459200,
3
v1=09efe4234a3cd00e44c20bcc00ef1b4f9d3f33ea87a7f04bc0d87fc0ef0f04e8,
4
v1=b36793a72f8bd71c8a165bd4b5aefb9fe9f5ac272ccbc8971c82c8c89cade770
Copied!
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
1
def verify_signature(signature: str, payload: str, secret: str) -> bool:
2
    verify_sig = hmac.new(
3
        key=secret.encode("utf-8"),
4
        msg=payload.encode("utf-8"),
5
        digestmod=hashlib.sha256
6
    ).hexdigest()
7
    return hmac.compare_digest(verify_sig, signature)
Copied!
​
Troubleshooting section
Preparsed body in Step 2 (not grabbing raw incoming data)
In express grab it before the framework parses it
​
Use an authorization header
Get the applicant's consent
Last modified 4mo ago
Export as PDF
Copy link
Contents
Request attempts
Webhook signatures
Signature verification