Webhooks – Overview - Kairo Connect Docs

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

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, Signature validation, and Language examples.