Webhooks for post and Krevaya Radar events
Get signed post.published, post.failed, and competitor.breakout events, verify the signature, and handle retries
Written by the Krevaya team · Updated
Webhooks push events from Krevaya to your own HTTPS endpoint, so your systems learn when a post publishes or fails without polling. They are included with Plus and up, alongside the API and MCP.
Events
| Event | Sent when | Payload |
|---|---|---|
post.published | A post published | post: id, platform, status, external_post_id, permalink_url, error, body_preview |
post.failed | A post failed to publish | The same post fields, with error filled in |
competitor.breakout | Krevaya Radar spots a breakout post from an account you track | competitor: platform, handle, permalink, engagement numbers, baseline, ratio, caption |
{
"event": "post.published",
"post": {
"id": "1234567890123456789",
"platform": "linkedin",
"status": "published",
"external_post_id": "PLATFORM_POST_ID",
"permalink_url": "https://www.linkedin.com/feed/update/EXAMPLE",
"error": null,
"body_preview": "The first 140 characters of the post"
}
}
IDs are strings. permalink_url can be null, for example on some Stories, so don't require it.
Register an endpoint
There is no Settings screen for webhooks right now. You register an endpoint with POST https://api.krevaya.com/webhooks, made with your signed-in Krevaya session. API keys and MCP connections can't create, list, or delete webhooks.
{
"url": "https://your-app.example/hooks/krevaya",
"events": ["post.published", "post.failed"]
}
- Leave out
eventsto receive all three. - The URL must be publicly reachable; private and internal addresses are refused. Use HTTPS.
- The 201 response includes
id,url,events, andsecret. Save the secret now:GET /webhooksnever shows it again. - You can have up to 5 endpoints.
DELETE /webhooks/{id}removes one. If your plan lapses, you can still list and delete endpoints but can't add new ones.
If you need help registering an endpoint, ask support in chat. If all you need is publishing results, you can poll with an API key instead (see the end of this article).
Verify every delivery
Each delivery carries X-Krevaya-Signature: sha256=<hex>. Compute HMAC-SHA256 with your secret's text (UTF-8, not hex-decoded) as the key and the raw request body as the message, then compare in constant time. Verify before you parse the JSON: a framework that re-serializes the body breaks the signature.
import hashlib, hmac
def is_valid(raw_body: bytes, signature_header: str, secret: str) -> bool:
expected = "sha256=" + hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature_header or "")
import { createHmac, timingSafeEqual } from 'node:crypto';
// rawBody must be a Buffer with the exact bytes received.
export function isValid(rawBody, signatureHeader, secret) {
const expected = Buffer.from('sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex'));
const received = Buffer.from(signatureHeader || '');
return received.length === expected.length && timingSafeEqual(received, expected);
}
Retries and duplicates
- Krevaya tries each delivery up to three times: immediately, then after 2 seconds, then after 8 seconds. Each attempt waits 5 seconds for your response.
- Network errors, HTTP 5xx, and HTTP 429 are retried. Any other response ends the delivery. Don't rely on a redirect.
- Return a 2xx as soon as you have stored the event, and do slow work afterward. Return 503 if you can't store it, so a retry can help.
- The same event can arrive more than once, and there is no delivery ID or timestamp in the payload. Deduplicate with
eventpluspost.idand your own stored state; a hash of the raw body identifies an exact repeat. - Webhooks are notifications, not an archive. After an outage on your side, check the posts you track with
GET /v1/posts/{id}.
Poll instead of receiving webhooks
With an API key that has View content, GET /v1/automation/events?brand_id=YOUR_BRAND_ID&after=0 returns one brand's post.published and post.failed events from the last 30 days, each with an event_id for deduplication. Save next_cursor and pass it as after next time. Krevaya Radar breakouts aren't in this feed.
If deliveries don't arrive
- Check that
GET /webhookslists the endpoint as active and thateventsincludes the event you expect. - Make sure your endpoint answers within 5 seconds from the public internet.
- A 400 when registering means the URL isn't public or you already have 5 endpoints. A 403 means your plan doesn't include webhooks.