Webhook payloads

The Feedjolt webhook event types and the headers that frame each delivery. Covers payload shape, the signature and event headers, idempotency, and stability.

Each webhook delivery is a POST application/json to your endpoint. The body is the event payload - there's no envelope wrapper; the event type and timestamp are in HTTP headers.

Headers

Content-Type: application/json
X-Feedjolt-Signature: sha256=<hex>
X-Feedjolt-Event: status.changed
X-Feedjolt-Timestamp: 2026-04-30T12:34:56.789012+00:00

Branch on X-Feedjolt-Event in your handler.

Event types

Event	When
`post.created`	A new post is created on a board you're subscribed to.
`post.merged`	A post is merged into another.
`post.moderated`	A draft post is approved or rejected.
`status.changed`	A post moves between statuses.
`comment.created`	A new comment is posted (public or internal).
`vote.threshold`	A post crosses a configured vote count.

These are the event types currently supported by the NotificationEventType enum in the backend. Additional events (post edits, deletions, comment edits, changelog publishes) are on the roadmap - vote them up.

Payload shape

The body is the same dict we use internally to render notifications. The exact field set varies by event type. The schemas live in the OpenAPI reference under the webhook section, since they share types with the API.

A representative status.changed body looks roughly like:

{
  "id": "evt_abc123",
  "post": {
    "id": "post_xyz",
    "title": "Add dark mode",
    "url": "https://feedjolt.com/p/acme/posts/post_xyz",
    "board_slug": "feature-requests"
  },
  "from_status": { "name": "Planned", "color": "#6366F1" },
  "to_status":   { "name": "In progress", "color": "#FB923C" },
  "actor":       { "type": "admin_user", "email": "[email protected]" }
}

Treat the id field as the idempotency key - see Retries.

Field stability

We don't currently version event payloads. If we need to make a breaking change we'll add a new event type alongside the old one and migrate at our own pace.
We may add fields to existing payloads without warning. Code defensively (don't fail on unknown keys).

Truncation

Long bodies (post body, comment body) are not truncated today; we send the full content. If your endpoint has a request-size limit, keep it generous. The 10-second delivery timeout is the more likely first failure.