Appearance
Signature Verification
You should verify the signature of every webhook delivery before processing the event.
Signature verification allows your application to confirm that:
- The webhook was sent by KMaker.
- The request payload has not been modified.
- The request was generated using the secret associated with your webhook.
How It Works
When a webhook is configured, KMaker provides a webhook secret.
KMaker uses this secret to generate a signature for each webhook request. The generated signature is included in the X-Kmaker-Signature header.
For example:
http
X-Kmaker-Signature: <signature>Your application uses the same webhook secret to independently calculate the expected signature and compares it with the signature received in the request.
text
KMaker
│
│ Payload + Webhook Secret
│ │
│ ▼
│ Generate
│ Signature
│ │
│ ▼
│ X-Kmaker-Signature
│
▼
Consumer
│
│ Payload + Webhook Secret
│ │
│ ▼
│ Generate
│ Expected Signature
│ │
│ ▼
│ Compare signatures
│
├── Match ───────► Process webhook
│
└── No match ────► Reject webhookWebhook Secret
The webhook secret is a sensitive credential used to generate and verify webhook signatures.
Store the secret securely on your server and never expose it in client-side applications or source code.
Do not:
- Commit the secret to source control.
- Include the secret in client-side code.
- Log the secret.
- Share the secret publicly.
Signature Header
The signature is provided in the following request header:
http
X-Kmaker-Signature: <signature>The signature is generated from the webhook payload and the webhook secret.
Signing Algorithm
KMaker signs each delivery with HMAC-SHA256. The digest is Base64-encoded using the standard alphabet and is sent in the X-Kmaker-Signature header.
| Element | Value |
|---|---|
| Algorithm | HMAC-SHA256 |
| Key | your webhook secret, used as raw UTF-8 bytes |
| Message | the raw JSON request body |
| Output encoding | Base64, standard alphabet (not URL-safe) |
| Header | X-Kmaker-Signature |
Signed Content
The signature is calculated over the JSON request body exactly as it is delivered — the whole event envelope, including eventId, eventType, createdAt, and data:
text
signature = Base64(HMAC-SHA256(webhookSecret, rawRequestBody))Nothing else forms part of the signed content. There is no timestamp component and no header is included, so a valid signature proves the body arrived unmodified, but it does not by itself show that the delivery is recent. Use eventId to detect duplicate deliveries, as described in Webhook Delivery.
The signature should be calculated using the original request payload. Do not modify, reformat, or re-serialize the payload before verification.
Verification Flow
Your webhook handler should verify the signature before processing the event.
A typical verification flow is:
- Read the raw request body.
- Read the
X-Kmaker-Signatureheader. - Retrieve the webhook secret associated with the endpoint.
- Generate the expected signature using the documented signing algorithm.
- Compare the expected signature with the received signature using a secure comparison method.
- Reject the request if the signatures do not match.
- Process the webhook only after successful verification.
text
Receive request
│
▼
Read raw request body
│
▼
Read X-Kmaker-Signature
│
▼
Generate expected signature
│
▼
Compare signatures
│
┌────┴────┐
│ │
Match Mismatch
│ │
▼ ▼
Process RejectExample
The following examples show the verification step in practice. In both cases the signature is calculated over the raw request body, before any JSON parsing.
Node.js
js
import crypto from "node:crypto";
// rawBody is the request body exactly as received, before any JSON parsing.
const expected = crypto
.createHmac("sha256", webhookSecret)
.update(rawBody)
.digest("base64");
const received = req.get("X-Kmaker-Signature");
const isValid =
received.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));Python
python
import base64
import hashlib
import hmac
# raw_body is the request body exactly as received, before any JSON parsing.
expected = base64.b64encode(
hmac.new(webhook_secret.encode("utf-8"), raw_body, hashlib.sha256).digest()
).decode("ascii")
received = request.headers["X-Kmaker-Signature"]
is_valid = hmac.compare_digest(received, expected)If the received signature and expected signature match, the request can proceed to event processing.
If they do not match, the request should be rejected.
Use the Raw Request Body
Signature verification should be performed against the original request body.
For example, avoid doing this before verification:
text
HTTP request body
↓
Parse JSON
↓
Serialize JSON again
↓
Verify signatureInstead, verify the original body first:
text
HTTP request body
│
├──────────────► Verify signature
│
▼
Parse JSON
│
▼
Process eventThis is important because changes in whitespace, property ordering, escaping, or serialization can produce a different signature.
Secure Comparison
Do not use a regular string comparison when comparing signatures if your language provides a constant-time or timing-safe comparison function.
Use the security primitives provided by your language or framework to compare the received and expected signatures.
Handling Invalid Signatures
If signature verification fails, do not process the event.
Your application should return an appropriate HTTP error response and record enough information to investigate the failure without logging sensitive credentials.
For example:
text
Invalid signature
│
├── Do not process event
├── Do not trust event data
└── Return an error responseTroubleshooting
If signature verification fails, check the following:
Verify the Webhook Secret
Make sure your application is using the secret associated with the correct webhook configuration.
Verify the Signature Header
Make sure your application is reading:
http
X-Kmaker-Signatureand not another header.
Verify the Request Body
Make sure the signature is calculated using the original request body and that the body has not been modified before verification.
Verify Encoding
Make sure your application encodes the digest with the Base64 standard alphabet, and that the signature is calculated over the raw request body bytes rather than over a parsed and re-serialized form of the payload.
Security Recommendations
- Always verify the signature before processing a webhook.
- Keep the webhook secret secure.
- Use HTTPS for webhook endpoints.
- Never log webhook secrets.
- Use constant-time or timing-safe signature comparison.
- Verify the raw request body before parsing or modifying it.