Routes, payloads, and errors
Fields, responses, and errors for the task, post, and comment routes, and how retries behave.
- PlanPro
- WhoOwners and admins
Routes and payloads
Send a JSON object to one of three routes on https://projectfeed.app. Every request is signed as described in Signing and security. The request body can be up to 256 KiB. A larger body returns 413.
POST /api/v1/webhooks/inbound/tasks
Create a task, or update the task with the same source and externalId.
sourcestringrequired- Short name of the sending system, such as github or ci.
externalIdstringrequired- The sender's stable ID for this item.
titlestringrequired- Task title. Longer than 200 characters is cut to 200.
projectIdstring- Project to create the task in. Required for a secret that covers all projects. A project secret uses its own project and rejects a different projectId.
descriptionstring- Plain text description.
statusstring- backlog, todo, in_progress, perpetual, in_review, done, or cancelled. New tasks default to backlog.
prioritystring- none, low, medium, high, or urgent. New tasks default to none.
assigneeEmailstring- Email of a workspace member to assign. An email that matches no active member is ignored.
dueDatenumber- Due date as a Unix timestamp in milliseconds.
{
"source": "ci",
"externalId": "build-1234",
"projectId": "prj_abc123",
"title": "Flaky CI on main",
"description": "Tests intermittently fail on the auth suite.",
"status": "todo",
"priority": "high",
"assigneeEmail": "alex@example.com"
}Returns 201 when the item is new and 200 when it updates an existing item. The status field in the response is created or updated.
{
"taskId": "tsk_abc123",
"identifier": "WEB-42",
"status": "created"
}identifier is null when the project has no identifier prefix. An update changes only the fields you send. It always sets the title.
POST /api/v1/webhooks/inbound/posts
Create a post, or update the post with the same source and externalId.
sourcestringrequired- Short name of the sending system.
externalIdstringrequired- The sender's stable ID for this post.
titlestringrequired- Post title. Longer than 500 characters is cut to 500.
projectIdstring- Project to create the post in. Required for a secret that covers all projects.
contentstring | object- Post body as plain text or rich text JSON. Empty when omitted and contentHtml is also omitted.
contentHtmlstring- Plain text body, used only when content is omitted. Markup is not rendered.
statusstring- draft or published. New posts default to draft.
{
"source": "perforce",
"externalId": "change-10421",
"title": "alex submitted changelist 10421",
"content": "Updated lighting and fixed the build.",
"status": "published"
}Returns 201 when the item is new and 200 when it updates an existing item. The status field in the response is created or updated.
{
"postId": "pst_abc123",
"identifier": "REL-18",
"status": "created"
}Changing the text of an existing post saves a new version. Sending published for a draft publishes it.
POST /api/v1/webhooks/inbound/comments
Add a comment to a post that an earlier request created, or update the comment with the same source and externalId.
sourcestringrequired- Short name of the sending system.
externalIdstringrequired- The sender's stable ID for this comment.
externalParentSourcestringrequired- The source of the post this comment belongs to.
externalParentIdstringrequired- The externalId of that post. The post must already exist. Send it to the posts route first.
contentstring | objectrequired- Comment body as plain text or rich text JSON. It cannot be empty and is limited to 128 KB.
{
"source": "ci",
"externalId": "build-1234-note-1",
"externalParentSource": "perforce",
"externalParentId": "change-10421",
"content": "Build passed on all platforms."
}Returns 201 when the item is new and 200 when it updates an existing item. The status field in the response is created or updated.
{
"commentId": "cmt_abc123",
"postId": "pst_abc123",
"status": "created"
}Comments attach to posts only. If no post matches the parent source and ID, the route returns 404. A secret for one project only finds parents in that project.
Each secret can send up to 1,000 requests a minute. Going over returns 429 with a Retry-After header. See rate limits.
Retries and duplicates
Project Feed treats source and externalId as the identity of an item within the workspace. The first request creates it. Later requests with the same pair update it, so a retry with a new signature never makes a duplicate. If the pair already belongs to an item in another project, the request returns 409.
Project Feed also rejects a request whose signature it has already accepted. If you retry the exact same signed request, you get 409 with the detail Duplicate request, which means the first attempt worked. To send the same item again, sign a new request with a fresh timestamp.
Errors
400- The body is not a JSON object, a required field is missing, or projectId is missing or does not match the secret's project.
401- A signature header is missing, the secret is unknown or revoked, the signature does not match, or the timestamp is more than 5 minutes from the server clock.
404- The project does not exist in this workspace, or the parent post for a comment was not found.
409- Duplicate request, or the source and externalId belong to an item in another project.
413- The body is larger than 256 KiB.
429- The secret went over 1,000 requests a minute.
Error bodies follow the format in API errors.