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:

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.

KMaker
   │
   │  Payload + Webhook Secret
   │          │
   │          ▼
   │      Generate
   │      Signature
   │          │
   │          ▼
   │  X-Kmaker-Signature
   │
   ▼
Consumer
   │
   │  Payload + Webhook Secret
   │          │
   │          ▼
   │      Generate
   │      Expected Signature
   │          │
   │          ▼
   │     Compare signatures
   │
   ├── Match ───────► Process webhook
   │
   └── No match ────► Reject webhook

Webhook 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:

X-Kmaker-Signature: <signature>

The signature is generated from the webhook payload and the webhook secret.

Signing Algorithm

To be documented: The signing algorithm used by KMaker.

Signed Content

To be documented: The exact content used to generate the signature.

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:

1. Read the raw request body.
2. Read the X-Kmaker-Signature header.
3. Retrieve the webhook secret associated with the endpoint.
4. Generate the expected signature using the documented signing algorithm.
5. Compare the expected signature with the received signature using a secure comparison method.
6. Reject the request if the signatures do not match.
7. Process the webhook only after successful verification.

Receive request
      │
      ▼
Read raw request body
      │
      ▼
Read X-Kmaker-Signature
      │
      ▼
Generate expected signature
      │
      ▼
Compare signatures
      │
 ┌────┴────┐
 │         │
Match    Mismatch
 │         │
 ▼         ▼
Process   Reject

Example

The following example illustrates the verification flow.

Secret:
<your-webhook-secret>

Request body:
<raw-request-body>

Received signature:
<signature-from-x-kmaker-signature>

Expected signature:
<signature-calculated-from-secret-and-payload>

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:

HTTP request body
      ↓
Parse JSON
      ↓
Serialize JSON again
      ↓
Verify signature

Instead, verify the original body first:

HTTP request body
      │
      ├──────────────► Verify signature
      │
      ▼
Parse JSON
      │
      ▼
Process event

This 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:

Invalid signature
      │
      ├── Do not process event
      ├── Do not trust event data
      └── Return an error response

Troubleshooting

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:

X-Kmaker-Signature

and 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 uses the encoding specified by the KMaker signing specification when calculating the signature.

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.