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

# Webhooks – Overview

> Register HTTPS endpoints to receive Kairo Shield events

Register a **public HTTPS URL** to receive POST events when relevant actions occur (transaction scored, alert, feedback received).

## API management

| Method | Path | Description |
| - | - | - |
| `POST` | `/api/v1/webhooks` | Create webhook (returns `secret` once) |
| `GET` | `/api/v1/webhooks` | List webhooks |
| `GET` | `/api/v1/webhooks/{id}` | Detail |
| `PUT` | `/api/v1/webhooks/{id}` | Update URL, events, retry policy |
| `DELETE` | `/api/v1/webhooks/{id}` | Delete |
| `GET` | `/api/v1/webhooks/{id}/logs` | Delivery history |
| `POST` | `/api/v1/webhooks/{id}/test` | Test payload |

**Authentication:** `X-API-Key` on all management routes.

## Your endpoint requirements

* **HTTPS** required
* Respond within **30 seconds**
* Return **200** (or other 2xx) when processed successfully
* Return **401** if signature is invalid
* **Idempotent** processing (use `X-Kairo-Delivery` to detect duplicates)

## Create webhook — example

```json theme={null}
POST {BASE_URL}/api/v1/webhooks

{
  "name": "Production – scoring",
  "url": "https://api.your-fintech.com/webhooks/kairo-shield",
  "events": ["transaction.scored", "transaction.high_risk", "feedback.received"],
  "description": "Production fraud events"
}
```

The **201** response includes the `secret` field **only on creation**. Store it securely; it is not shown again.

See [Events](/docs/shield/webhooks/events), [Signature validation](/docs/shield/webhooks/validation), and [Language examples](/docs/shield/webhooks/signature-verification).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.