Analytics and integrations · 7 / 7 · 4 min

API and webhooks: integrating with your website

API keys, creating jobs, fetching videos and articles, signed webhooks and automatic article publishing on your site.

The API lets you do almost everything available in the dashboard: create production jobs, fetch finished videos and articles, add plan items and read trends. Webhooks notify you about events, so your system doesn’t have to poll.

API key

  1. Open “Project settings → Integrations → API keys”.
  2. Click “Create key” and name it: “Website”, “CRM”.
  3. Copy the key — it is shown once. We store only its hash.

A key works only for its own project. If a key leaks, revoke it and create a new one. The API is available on plans with integrations; plan limits also apply to jobs created via the API.

Requests

Send the key in the X-Api-Key header. All responses are JSON.

GET  /api/v1/project                 — project details
POST /api/v1/jobs                    — create a job
GET  /api/v1/jobs/{id}               — job status
GET  /api/v1/videos?status=approved  — videos
GET  /api/v1/videos/{id}
GET  /api/v1/articles?status=approved
GET  /api/v1/articles/{id}
POST /api/v1/plan                    — add a plan item
GET  /api/v1/trends?limit=20         — trends

Example: cutting a video by URL

POST /api/v1/jobs
X-Api-Key: kdx_...
Content-Type: application/json

{
  "type": "clip_cut",
  "params": {
    "source": {"url": "https://example.com/webinar.mp4"},
    "count": 8, "min_sec": 20, "max_sec": 45,
    "platforms": ["youtube", "vk"]
  }
}

The response contains the job id and status: "queued". Then either poll GET /api/v1/jobs/{id} or subscribe to the job.succeeded webhook.

Webhooks

In “Integrations → Webhooks” add a URL and choose events. The main ones:

Event When it fires
job.succeeded, job.failed A job finished
video.ready_for_review A video is ready for review
video.approved, video.rejected A video was approved or rejected
article.approved An article was approved — with full text and HTML
post.published, post.failed A post went live or failed
plan.generated A new plan is ready
trend.alert A trend crossed your threshold

Delivery format

Each event is a POST with JSON and headers:

  • X-Kadrix-Event — the event name;
  • X-Kadrix-Delivery — the delivery ID;
  • X-Kadrix-Signature — sha256= plus an HMAC-SHA256 of the body using your secret.

Verify the signature before processing. Python example:

import hmac, hashlib

def verify(secret: str, body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

Reply with a 2xx code within 10 seconds. Otherwise delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours. Delivery history and a “Send test” button are on the webhook card.

Articles on your site automatically

The article.approved event contains everything needed to publish without manual work: title, slug, lang, html and body_md, meta for search engines, image links and keywords.

A typical setup: your site has a webhook handler that verifies the signature, creates an entry in your CMS and publishes it. Approve an article in the dashboard or in Telegram — a minute later it is on your site. If article warnings are enabled in the project, they are already inserted into html at the chosen placement.

Handing videos to other services

The video.approved webhook contains the file link, cover and per-platform captions. This is how videos reach systems that aren’t built-in platforms — for example, pin publishing tools.

Security

  • Keep keys and webhook secrets on the server, never in front-end code.
  • Use HTTPS webhook URLs.
  • Make your handler idempotent: the same delivery may arrive twice — use X-Kadrix-Delivery.

Next steps