Webhooks

Orkestra supports webhooks in both directions. Outbound: we notify you when something changes. Inbound: your external service creates tasks or updates states. Both available from the Organization plan.

Outbound webhooks

When an event happens in your organization (task created, state changed, comment added, etc.), Orkestra sends a POST to the URL you configure. Events are HMAC-signed so you can verify they come from Orkestra.

Supported events

Main events you can subscribe to:

• task.created — new task created
• task.updated — any field updated
• task.state_changed — workflow state change
• task.assigned — assignment or reassignment
• task.deleted — task deleted
• project.created, project.archived, project.deleted
• wiki.page_updated — wiki page edit
• comment.created — new comment on task or wiki
• member.joined, member.removed

Payload format

Each webhook receives a JSON with this structure:

• id — unique event ID (for idempotency)
• type — event name (e.g. task.state_changed)
• createdAt — ISO 8601 timestamp
• organizationId — ID of the org where it happened
• data — object with the affected resource and, if applicable, previous with the prior state

HMAC verification

Each request includes an X-Orkestra-Signature header with an HMAC-SHA256 of the body using your webhook secret. To verify:

1. Take the raw body of the request (unparsed).
2. Compute HMAC-SHA256(body, your_secret).
3. Compare with the header in constant time (use crypto.timingSafeEqual in Node).

Smart retry

Orkestra retries failed deliveries with this logic:

• 5xx / timeout: retry with exponential backoff (1s, 5s, 30s, 2min, 10min, 1h).
• 4xx (except 429): permanent failure, no retry. You'll see the error in the log.
• 429: respects Retry-After if you send it, or applies exponential backoff.
• After 6 failed attempts, the webhook is marked as failed and the admin is notified.

Inbound webhooks

Inbound webhooks let you create tasks or update states from external services. They're compatible with Zapier and Make, or you can call them directly from your code.

Setup

From Settings → Inbound webhooks → New:

1. Choose the target project.
2. Define the field mapping (e.g. payload's title → Orkestra's title).
3. Copy the generated URL and API key.
4. Configure your external service to POST with the mapped payload.

Auth

Inbound webhooks authenticate with the X-Orkestra-Api-Key header. The key is unique per webhook and revocable. It's stored SHA-256 hashed.

Monitoring

Every webhook (inbound and outbound) has a log with the last 30 days of activity: status, latency, payload, response. Useful for debugging when something isn't working.