Callbacks and inbound

Callbacks and inbound

Two related surfaces let an extension act on tasks without a user API key.

Canonical paths are under /api/v2. /api/v1 remains a compatibility alias (Ordryn 4.0.0).

Callback tokens (permissions)

Declaring any permissions mints a project-scoped callback token (prefix odycb_). JSON http.webhook deliveries then include callback_token and callback_url. This is not a user API key.

Permission	Callback actions it unlocks
tasks:read	get
tasks:write	complete, set_field
comments:write	comment

Rotate the token from the project Extensions tab (controls: rotate_callback). The value is shown once.

POST /api/v2/ext/callback

Authorization: Bearer odycb_…
Content-Type: application/json

{
  "action": "get",
  "task_id": 42,
  "comment": "optional",
  "field": "callback-bot.notes",
  "value": "optional"
}

action	Required fields	Result
get	task_id	Task snapshot: id, title, completed, priority, project_id, project, status, due_date, sprint, claimed_by, tags, fields
complete	task_id	Marks the task completed
comment	task_id, comment	Posts a discussion comment
set_field	task_id, field	Writes a custom field ({extension_id}.{key}). Empty value clears it.

The token can only see tasks in its project. Rate limit: 60 requests / minute per IP+bearer.

callback-bot is the working example: outbound JSON includes the token; relay/main.go comments on task.due_soon and sets callback-bot.review_by on create.

Do not put the token in the sandboxed panel.

Inbound webhook (actions)

The project inbound webhook is a first-party feature (POST /api/v2/webhooks/inbound). First-party flags still control create and comment.

Manifest actions opt a site- and project-enabled extension into extra verbs on that same endpoint:

Action	Required JSON	Effect
complete	project_id, task_id	Completes the task
comment	(first-party comment flag)	Posts a comment when the project inbound comment flag is on
set_field	project_id, task_id, field	Writes a custom field

JSON must include project_id. The task must belong to that project.

Auth

Either:

• X-Ordryn-Webhook-Secret: <shared secret>, or
• HMAC: X-Ordryn-Timestamp (unix seconds, ±5 minutes) and X-Ordryn-Signature: sha256=HMAC(secret, timestamp + "." + body)

Rate limit: 30 requests / 0.5 minutes per IP.

Inbound HMAC is not the same as outbound webhook signing (rotate_signing signs only the raw body). See Delivery.

Example manifest block

{
  "permissions": ["tasks:read", "tasks:write", "comments:write"],
  "actions": ["complete", "comment", "set_field"],
  "controls": ["send_test", "rotate_signing", "rotate_callback", "sample_json"]
}