Events (Webhook Subscriptions)

Subscribe to event notifications delivered to a URL you control.

The datafeed.source.* event family is a public abstraction over the internal datasource.* events; the gateway transparently maps event names, filters, and delivered payloads in both directions, so you always work in the datafeed.source.* / datafeed-id terms.

`POST /events/subscriptions`

Request body:

Field	Type	Notes
`name`	string	subscription label
`url`	string	required — your callback URL
`events`	string[]	required — event names to subscribe to; see Which events exist below
`httpOperation`	string	`POST` (default) or `GET` — how the callback is delivered
`filters`	object	optional; e.g. `{ "resourceId": "<datafeedId>" }` for `datafeed.source.*` events

Which events exist

Family	Status
`metric.*`	Working
`dashboard.*`	Working
`tag.*`	Working
`goal.*`	Not available yet
`datafeed.source.*`	Not reliable yet — avoid depending on delivery

Check with your Klipfolio contact for events not listed here.

{
  "name": "My Webhook",
  "url": "https://my.webhook.url/b0945fa0",
  "events": ["metric.created"],
  "httpOperation": "POST"
}

Responses:

201 — a single created subscription, wrapped in the meta/data envelope described in Getting Started (meta.url is /events/subscriptions/<id>). A request that produced more than one subscription (mixing datafeed.source.* with other events) has no single resource for meta.url to name, so that case returns a bare array of subscriptions instead, with no envelope.

The created subscription also carries a signingSecret field, returned only this once — it is not included in any later GET, so save it when you receive it. Use it to verify a delivered payload is genuinely from Klipfolio: each delivery carries an x-klipfolio-signature header containing HMAC-SHA256(signingSecret, JSON.stringify(payload)), hex-encoded. Recompute it yourself and compare against the header before trusting a delivery.

207 Multi-Status — partial success when a request that fans out into multiple subscriptions (e.g. mixing datafeed.source.* and other events) has some succeed and some fail:

{
  "created": [ { "id": "sub_1", "events": ["metric.created"], "url": "https://my.webhook.url/b0945fa0" } ],
  "errors": [ { "events": ["datafeed.source.refreshed"], "status": 400, "message": "..." } ]
}

A whole-request failure returns the normal single error status.

`GET /events/subscriptions`

List your subscriptions (array). Abstraction webhooks are mapped back to the public shape (your original URL, method, events, and datafeed id).

`GET /events/subscriptions/:subscriptionId`

Return a single subscription in the public shape.

{
  "id": "sub_1",
  "name": "My Webhook",
  "url": "https://my.webhook.url/b0945fa0",
  "events": ["metric.created"],
  "httpOperation": "POST"
}

`DELETE /events/subscriptions/:subscriptionId`

204 No Content.