Webhook Delivery

KMaker delivers webhook events to the endpoint configured for your webhook registration using HTTP POST requests.

This page describes the webhook request format, idempotency, delivery retries, and expected responses.

Request Format

A webhook delivery is sent as an HTTP POST request with a JSON request body.

POST /webhooks/example HTTP/1.1
Content-Type: application/json
X-Kmaker-Signature: <signature>
X-Idempotency-Key: <event-id>

Headers

Header	Description
Content-Type	Indicates that the request body contains JSON.
X-Kmaker-Signature	Signature generated for the webhook payload. Used to verify the authenticity and integrity of the request. See Signature Verification.
X-Idempotency-Key	Unique identifier for the webhook event. The value is the same as eventId in the request body.

Request Body

The request body contains the standard webhook event envelope:

{
  "eventId": "d42a2f74-a2dd-4080-8645-d681cc490eaa",
  "eventType": "ALERT:CREATED",
  "createdAt": "2026-08-18T13:20:27.400518",
  "data": {
    "object": {},
    "previousAttribute": {}
  }
}

For more information about the event envelope and event-specific payloads, see Webhook Events.

---

Idempotency

Webhook deliveries should be treated as at-least-once delivery. The same event may be delivered more than once, for example when a previous delivery fails or times out.

Each event has a unique eventId, which is also provided as the X-Idempotency-Key header.

X-Idempotency-Key: d42a2f74-a2dd-4080-8645-d681cc490eaa

The same identifier is available in the request body:

{
  "eventId": "d42a2f74-a2dd-4080-8645-d681cc490eaa"
}

Your application should use this identifier to ensure that the same event is not processed more than once.

Example

First delivery
    eventId: abc-123
          │
          ▼
    Process event
          │
          ▼
    Store abc-123

Duplicate delivery
    eventId: abc-123
          │
          ▼
    Already processed
          │
          ▼
    Ignore duplicate

Do not generate a new idempotency key for a webhook event. Use the eventId provided by KMaker.

---

Retries

KMaker may retry a webhook delivery when the delivery cannot be completed successfully.

Retries are intended to handle temporary failures such as connection failures or server-side errors.

Each retry represents the same webhook event and therefore uses the same eventId and X-Idempotency-Key.

For example:

Attempt 1
eventId: abc-123
      │
      └── Failed

Attempt 2
eventId: abc-123
      │
      └── Failed

Attempt 3
eventId: abc-123
      │
      └── Successful

Because retries use the same event ID, webhook consumers must implement idempotent event processing.

Current Retry Behavior

KMaker currently retries eligible failed deliveries up to 3 retry attempts, with a backoff between attempts.

Retries are currently triggered for:

• Server-side (5xx) errors
• Connection failures

Client-side (4xx) errors are not retried.

Retry behavior may be updated as the webhook delivery system evolves. Consumers should always rely on eventId for idempotent processing rather than assuming a webhook will be delivered exactly once.

---

Responses

Your webhook endpoint should return an HTTP response after receiving a delivery.

Successful Response

Return a 2xx status code when the webhook has been successfully accepted.

For example:

HTTP/1.1 200 OK

A successful response indicates that KMaker does not need to retry the delivery.

Client Errors

A 4xx response indicates that the request could not be accepted by the consumer.

These responses are not retried.

For example:

HTTP/1.1 400 Bad Request

Server Errors

A 5xx response indicates a temporary server-side failure.

These responses may trigger a retry.

For example:

HTTP/1.1 500 Internal Server Error

Processing Recommendations

Webhook endpoints should respond as quickly as possible.

If event processing is time-consuming, consider:

1. Validating the request.
2. Recording the event.
3. Returning a successful response.
4. Processing the event asynchronously.

Ensure that the event is safely recorded before acknowledging it so that the event can be recovered if processing fails.

---

Delivery Summary

Behavior	Description
Method	POST
Content type	application/json
Event identifier	eventId
Idempotency header	X-Idempotency-Key
Signature header	X-Kmaker-Signature
Successful response	2xx
Client error	4xx, not retried
Server error	5xx, may be retried
Duplicate deliveries	Must be handled using eventId
Retry attempts	Up to 3 retries for eligible failures