# Webhooks and API keys

Webhooks deliver play, complete, cta_click and lead events to any HTTPS endpoint as JSON, signed with HMAC-SHA256 in an x-videokr-signature header so you can verify the payload. API keys authenticate read access to your account, library and insights — that is how the WordPress plugin connects.

- Section: Documentation (https://videokr.com/docs)
- Page: https://videokr.com/docs/webhooks-and-api
- Last updated: 2026-08-18

## Webhooks

Add an endpoint under **Integrations**, choose which events it receives, and Videokr POSTs JSON to it. A test delivery button proves the endpoint before a real lead depends on it, and the last status and error are shown so a silently broken endpoint does not stay broken.

Events:

- `play` — a viewer started a video.
- `complete` — a viewer reached the end.
- `cta_click` — an overlay, banner or end-screen action was clicked.
- `lead` — an email was submitted in the player.

## Verifying a delivery

Each request carries `x-videokr-signature`: the hex HMAC-SHA256 of the exact request body, keyed with the endpoint's secret. Compare it against your own computation on the raw body before trusting the payload.

```js
const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header))) return res.sendStatus(401);
```

Verify the raw body, not a re-serialised object — re-encoding JSON changes the bytes and breaks the signature.

## API keys

Create a key under **Integrations**. Send it as `Authorization: Bearer vk_...` to the `/api/v1` endpoints, which return your account and plan usage, your video and playlist library, insights and leads. Keys are read-only, shown once, and revocable — revoking a key cuts off whatever was using it immediately, including a WordPress site.

Keep keys server-side. A key pasted into front-end JavaScript is a public key.

## Rate and scope

One key per integration is the sane pattern: it means you can revoke the WordPress site without breaking your internal dashboard. Keys are scoped to your account and cannot read another account's data.

## FAQ

### How do I verify a webhook is really from Videokr?

Recompute HMAC-SHA256 of the raw request body with the endpoint secret and compare it to the x-videokr-signature header using a timing-safe comparison.

### Are API keys read-only?

Yes. They authenticate reads of your account, library, insights and leads — they cannot change or delete anything.

## Related

- [WordPress plugin: install, connect, embed](https://videokr.com/docs/wordpress-plugin)
- [Analytics: plays, completions and the retention curve](https://videokr.com/docs/analytics)
- [CTAs, overlays, end screens and email gates](https://videokr.com/docs/ctas-and-lead-forms)
- [Quickstart: host a video and embed it](https://videokr.com/docs/quickstart)

---
Videokr — Videokr is hosted video for marketing sites: upload or link a video, brand the player, capture emails inside it, embed it anywhere and read second-by-second retention. Free tier forever, $69 lifetime, or metered plans.
Plans: https://videokr.com/#pricing · Full reference: https://videokr.com/llms-full.txt