Skip to main content
Webhooks deliver real-time POSTs to your endpoint whenever something happens in your Sleekplan workspace. Use them to mirror data, automate workflows, or connect Sleekplan to tools without a native integration.

Use cases

  • Store new feedback items directly in your own database.
  • Capture a visitor’s email address the moment they set it.
  • Trigger a Slack message or Zapier workflow when a user votes, comments, or subscribes to a suggestion.
  • Sync changelog publishes to an external CMS or mailing list.

1

Create a public HTTP endpoint

Set up a server endpoint that accepts POST requests and returns a 2xx HTTP status to acknowledge receipt.Secure your endpointAppend a secret key as a GET parameter to your endpoint URL, then validate the parameter server-side before processing the payload:
Sleekplan does not sign webhook payloads with an HMAC signature. Using a secret GET parameter is the recommended way to verify that requests originate from Sleekplan.
2

Register the webhook

  1. Open your product Settings.
  2. Navigate to the Developer section.
  3. Scroll to Webhooks, click Add webhook.
  4. Enter your endpoint URL (with the ?key= parameter).
  5. Save. Sleekplan starts delivering events immediately.

Delivery

Each event is sent as a POST with a JSON body and the user agent Sleekplan-Webhooks.
  • Your endpoint must answer with a 2xx status within 10 seconds. Any other answer counts as a failed delivery.
  • Redirects aren’t followed, so register the final URL.
  • Sleekplan only delivers to public addresses, never to localhost or a private network.
  • Failed deliveries aren’t retried.
  • Each event is its own delivery. Events can arrive out of order and, rarely, twice, so use the IDs and timestamps in the payload to reconcile them.
  • Sleekplan doesn’t send webhooks from a fixed IP address. Verify requests with your ?key= secret, not with an IP allowlist.
If the last delivery failed, the webhook shows Delivery failing in Settings → Developer, together with the reason. The status stays for three days and clears with the next successful delivery.

Events

A webhook receives every event unless you pick the events it listens to when you add or edit it. Some events have a specific version next to the generic one, and a change sends both. A status change, for example, sends item.update and item.status_update, and a document’s status change sends document.update and document.status_update. A webhook that listens to both gets both, so pick the specific event when that one change is all you need. Specific events are only sent when the value really changes. Changes that move many records at once send no events. When you delete a status, category or component, the feedback items moved to another one send none, and the same goes for the entries of a deleted changelog category and the documents of a deleted document type. Deleting a tag removes it from its feedback items without item.tags_update events. Deleting a document, a feedback item or a work item sends no unlink events for its document links. The bulk deletes in Settings → General differ: Delete all feedback posts still sends item.delete for each feedback item, but Delete all changelog updates sends no changelog.delete. Deleting a single changelog entry always sends it.

Feedback and suggestion events

A feedback item created with a status or with tags sends item.update next to item.create, and with it item.status_update (from open) or item.tags_update (from an empty list).

Other events

changelog.publish, changelog.unpublish and changelog.delete send the entry in data, the same as changelog.update, also when an entry goes live or is unpublished on its date. For changelog.delete, that’s the entry as it was before it was deleted.

Group events

Document events

A document that’s already linked to a work item as evidence and then becomes its spec or plan sends no new document.work_item_link: its role changes, but no new link is created.

Work item events

Notes and progress reports on a work item don’t send a webhook.

Payload format

General structure

Example: item.create

Example: item.status_update

The specific feedback item events send the same data as item.update, the whole feedback item, plus a change object with the value before and after. This example shows only some of the feedback item’s fields:
A merge sends item.update, item.status_update (to merged) and item.merge.

Example: group.update

A group event’s data holds the group with the same fields as the Groups endpoints:
  • On group.update, change.fields lists what changed: name, type, weight, mrr or meta. An update that changes none of them sends no event.
  • group.create and group.delete carry no change. group.delete sends the group as it was before it was deleted.
  • meta is always an object, {} when the group has no custom data.

Example: document.status_update

A document event’s data holds the document as the List documents endpoint returns it, without its content. To read the content, retrieve the document.
  • On document.update, change.fields lists what changed: title, content, document_type, tags or status.
  • document.type_update and document.status_update carry change.from and change.to.
  • document.feedback_link and document.feedback_unlink carry feedback_id, the feedback item the document was linked to or unlinked from.
  • document.work_item_link and document.work_item_unlink carry work_item (its number, key and title) and role: spec, plan or evidence.
  • document.delete sends the document as it was before it was deleted.

Example: work_item.completed

A work item event’s data holds the work item and what changed:
  • change.type is what happened: created on both events a new work item sends (work_item.create and work_item.needs_decision), updated on work_item.update, a decision such as complete or close, or a report from whoever works on the item, such as plan_ready or pr_merged. kind is system, decision or report.
  • channel says where the change came from (app, api, mcp or system), and agent names the agent that sent it, if there was one.
  • When the status changes, from_status and to_status show it before and after. The two events a new work item sends carry neither.
  • On work_item.update, fields lists what changed, for example ["title", "priority"]. It is ["feedback"] when posts are linked or unlinked, and ["evidence"] when evidence is added or removed.
The shape of the data field matches the corresponding REST API response. See the REST API reference for the full structure of each payload type.