> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.iklim.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Endpoint Guide

> Authentication and response requirements shared across all iklim.co webhook alarm deliveries.

## Incoming request authentication

When iklim.co delivers an alarm to your webhook endpoint, it attaches the credentials you configured during alarm registration. The exact mechanism depends on the authentication type you selected:

| Auth type                        | How credentials are sent                                                          |
| -------------------------------- | --------------------------------------------------------------------------------- |
| **Basic**                        | `Authorization: Basic <base64(username:password)>` header                         |
| **API Key — as header**          | `X-API-Key: <your-api-key>` header                                                |
| **API Key — as query parameter** | `?apiKey=<your-api-key>` appended to the URL                                      |
| **JWT**                          | `Authorization: Bearer <jwt-token>` header                                        |
| **HMAC Signature**               | `X-Client-Id`, `X-Signature`, `X-HmacAlgorithm`, `X-Timestamp`, `X-Nonce` headers |

<Tip>
  If you chose **API Key** authentication, exactly one of the two delivery modes (`asHeader` or `asQueryParameter`) is active — never both at the same time.
</Tip>

***

## Your endpoint's response

After receiving an alarm payload, your webhook endpoint must respond with HTTP `200` and a JSON body conforming to the `AlarmReceived` schema. iklim.co uses both the HTTP status code and the body-level `status` field to decide whether delivery was successful or should be retried.

<Tabs>
  <Tab title="Expected response 💾" icon="code">
    ```json theme={null}
    {
      "id": "a1b2c3d4-0000-4e5f-9876-000000000001",
      "status": "SUCCESS",
      "timeEpochMillis": 1726286415123
    }
    ```
  </Tab>

  <Tab title="Response fields 📚" icon="table-list">
    | Field             | Type   | Description                                                                                                                                                                                                             |
    | ----------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `id`              | string | Echo back the `id` from the received alarm payload exactly as-is. iklim.co compares this value against the dispatched alarm's `id` for correlation — a mismatch is treated as a transient failure and triggers a retry. |
    | `status`          | enum   | Processing outcome reported by your endpoint (see status table below).                                                                                                                                                  |
    | `timeEpochMillis` | number | Unix epoch timestamp in milliseconds at which your endpoint processed the alarm.                                                                                                                                        |

    #### `Status` values

    | Value       | Meaning                                                             | iklim.co action                        |
    | ----------- | ------------------------------------------------------------------- | -------------------------------------- |
    | `SUCCESS`   | Alarm was received and processed successfully.                      | Stop retrying, move to the next alarm. |
    | `CANCELLED` | Your system has opted out of further deliveries for this alarm.     | Stop retrying, move to the next alarm. |
    | `FAILURE`   | Transient error on your side (e.g. downstream service unavailable). | Run retry policy.                      |
    | `TIMEOUT`   | Your endpoint timed out internally while processing the alarm.      | Run retry policy.                      |
    | `UNKNOWN`   | Unexpected condition; cause is unclear.                             | Run retry policy.                      |
  </Tab>

  <Tab title="HTTP status matrix 🔍" icon="list-check">
    iklim.co evaluates the HTTP status code **before** inspecting the response body. Non-2xx responses never reach body-level evaluation.

    | HTTP | Body status              | Reason                             | Action        |
    | ---- | ------------------------ | ---------------------------------- | ------------- |
    | 200  | `SUCCESS`                | Processed successfully             | Stop retrying |
    | 200  | `CANCELLED`              | Endpoint opted out                 | Stop retrying |
    | 200  | `FAILURE`                | Transient recipient-side error     | Retry         |
    | 200  | `TIMEOUT`                | Recipient-side timeout             | Retry         |
    | 200  | `UNKNOWN`                | Unexpected recipient-side error    | Retry         |
    | 200  | id mismatch or null body | Correlation check failed           | Retry         |
    | 400  | —                        | Payload corrupted / missing fields | Retry         |
    | 401  | —                        | Authorization invalid or missing   | Stop retrying |
    | 403  | —                        | Access denied                      | Stop retrying |
    | 404  | —                        | Endpoint resource not found        | Stop retrying |
    | 405  | —                        | HTTP method not allowed            | Stop retrying |
    | 429  | —                        | Rate limit exceeded                | Retry         |
    | 500  | —                        | Unexpected server-side error       | Retry         |
    | 502  | —                        | Invalid upstream response          | Retry         |
    | 503  | —                        | Service temporarily unavailable    | Retry         |
    | 504  | —                        | Upstream gateway timeout           | Retry         |
  </Tab>
</Tabs>