Use webhooks
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.
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.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.Secrets are team-specific
Generate a secret for each team that uses your API.
When verifying the signatures of calls against multiple teams, use the
Certn-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.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 stringThe
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)
Troubleshooting section
- Preparsed body in Step 2 (not grabbing raw incoming data)
- In express grab it before the framework parses it
Last modified 9mo ago