Webhooks

Create and manage webhooks for feature flag events. Webhooks send HTTP POST requests to your URL when flag events occur, enabling real-time integrations.

Base URL: https://app.krafter.dev/api/v1

Signing, retry policy, and auto-disable rules are shared across the platform — see Webhook delivery.

List Webhooks

Retrieve all webhooks for a project.

GET /flags/webhooks?project_id=...

Required scope: flags:read

Query Parameters

Parameter	Type	Required	Description
project_id	string	Yes	Project to list webhooks for.

Example Request

curl "https://app.krafter.dev/api/v1/flags/webhooks?project_id=a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d" \
  -H "Authorization: Bearer kr_live_abc123def456"

Example Response

{
  "data": [
    {
      "id": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a",
      "url": "https://example.com/webhooks/flags",
      "events": ["flag.created", "flag.updated", "flag.toggled", "flag.archived", "flag.deleted"],
      "enabled": true,
      "failure_count": 0,
      "created_at": "2025-03-10T12:00:00Z",
      "updated_at": "2025-03-10T12:00:00Z"
    },
    {
      "id": "5e6f7a8b-9c0d-4e1f-9a2b-3c4d5e6f7a8b",
      "url": "https://slack.example.com/hooks/flags",
      "events": ["flag.toggled"],
      "enabled": true,
      "failure_count": 2,
      "created_at": "2025-03-11T15:30:00Z",
      "updated_at": "2025-03-15T10:00:00Z"
    }
  ]
}

---

Create Webhook

Create a new webhook for flag events.

POST /flags/webhooks

Required scope: flags:write

Request Body

Field	Type	Required	Description
project_id	string	Yes	Project this webhook belongs to.
url	string	Yes	The endpoint URL to receive webhook payloads. Both http:// and https:// are accepted; HTTPS is strongly recommended in production so signatures and payloads cannot be observed in transit. Private and internal addresses (RFC 1918, localhost, *.local, *.internal, link-local, IPv6 ULA/link-local) are rejected by UrlValidator for SSRF protection.
secret	string	No	Secret used to sign webhook payloads with HMAC-SHA256. Strongly recommended in production. When omitted (or empty), the x-krafter-signature header is not sent — receivers cannot verify the payload origin.
events	string[]	Yes	List of events to subscribe to. See Event Types.
enabled	boolean	No	Whether the webhook is active. Defaults to true.

Event Types

The event name is delivered in the x-krafter-event header; the body is the JSON payload below (no envelope around it).

Event	When fires	Payload fields
flag.created	A new flag was created.	flag_id, key, name
flag.updated	A flag's configuration was modified (name, description, default value, rules, etc.).	flag_id, key
flag.toggled	A flag was enabled or disabled (manual or scheduled).	flag_id, key, enabled
flag.archived	A flag was archived. Evaluations of archived flags return the caller's default value until the flag is unarchived or deleted.	flag_id, key
flag.deleted	A flag was permanently deleted.	flag_id, key

Example body — flag.toggled

{
  "flag_id": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
  "key": "new-checkout-flow",
  "enabled": false
}

Example Request

curl -X POST https://app.krafter.dev/api/v1/flags/webhooks \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "url": "https://example.com/webhooks/flags",
    "secret": "whsec_a1b2c3d4e5f6g7h8i9j0",
    "events": ["flag.created", "flag.updated", "flag.toggled", "flag.archived", "flag.deleted"]
  }'

Example Response

// 201 Created
{
  "data": {
    "id": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a",
    "url": "https://example.com/webhooks/flags",
    "events": ["flag.created", "flag.updated", "flag.toggled", "flag.archived", "flag.deleted"],
    "enabled": true,
    "failure_count": 0,
    "created_at": "2025-03-10T12:00:00Z",
    "updated_at": "2025-03-10T12:00:00Z"
  }
}

---

Update Webhook

Update an existing webhook. Only provided fields are changed.

PATCH /flags/webhooks/:webhook_id

Required scope: flags:write

Request Body

Field	Type	Required	Description
url	string	No	The endpoint URL to receive webhook payloads.
secret	string	No	New secret for signing webhook payloads.
events	string[]	No	List of events to subscribe to.
enabled	boolean	No	Whether the webhook is active.

Example Request

curl -X PATCH https://app.krafter.dev/api/v1/flags/webhooks/5e6f7a8b-9c0d-4e1f-9a2b-3c4d5e6f7a8b \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["flag.toggled", "flag.deleted"],
    "enabled": true
  }'

Example Response

{
  "data": {
    "id": "5e6f7a8b-9c0d-4e1f-9a2b-3c4d5e6f7a8b",
    "url": "https://slack.example.com/hooks/flags",
    "events": ["flag.toggled", "flag.deleted"],
    "enabled": true,
    "failure_count": 2,
    "created_at": "2025-03-11T15:30:00Z",
    "updated_at": "2025-03-16T17:00:00Z"
  }
}

---

Delete Webhook

Permanently delete a webhook. No further events will be delivered to this endpoint.

DELETE /flags/webhooks/:webhook_id

Required scope: flags:write

Example Request

curl -X DELETE https://app.krafter.dev/api/v1/flags/webhooks/5e6f7a8b-9c0d-4e1f-9a2b-3c4d5e6f7a8b \
  -H "Authorization: Bearer kr_live_abc123def456"

Example Response

// 204 No Content