Webhooks

Subscribe to entity events, verify signatures and deduplicate safely by event ID.

Application revision 8c09715b · Docs d2d4fba5

    Configure an endpoint

    Workspace administrators add a public HTTPS receiver in Webhook settings and select event types. Server-side encryption must be configured first. Delivery respects current team access; workspace administration does not automatically grant private-team events.

    Supported events are created, updated, and deleted for issues, comments, projects, and cycles. Each event contains id, type, workspaceId, entityId, and occurredAt. Comment events also carry IDs that let you fetch the comment.

    Read a comment from an event

    For comment.created, comment.updated, and comment.deleted, entityId is the internal comment ID. After verifying the signature, pass the event’s workspaceId as the X-Workspace-Id header and use an API key with read access to the resource.

    Comment source IDs in the event Read the comment
    Issue issueId GET /api/issues/{issueId}/comments, then match the item’s id to entityId. You can also pass issueId to the MCP get_issue tool.
    Project description projectId GET /api/projects/{projectId}/comments/{entityId}
    Project update projectId and projectUpdateId GET /api/projects/{projectId}/updates/{projectUpdateId}/comments/{entityId}

    Use the IDs in delete events to clear cached references. If a comment has already been deleted, it may be absent from the list or return 404 on a direct lookup. Retries and replays keep the original payload, so older events can arrive without the resource IDs.

    Store the signing secret

    Creating or editing an endpoint returns its signing secret once. Store it immediately in the receiver’s secret store; normal lists do not expose it again. Editing rotates the secret and configuration revision and cancels queued deliveries for the old revision. Old events are not redirected to a new URL.

    Reload conflicting configuration instead of overwriting another administrator’s changes. Deleting an endpoint or revoking access cannot recall a request already sent.

    Verify the raw request

    Read these headers and verify the original body before parsing or reordering JSON:

    X-Task-Manager-Event-Id
    X-Task-Manager-Timestamp
    X-Task-Manager-Signature: sha256=<hex>
    
    HMAC-SHA256(signingSecret, eventID + "." + timestamp + "." + rawBody)

    Compare signatures in constant time, limit timestamp skew and deduplicate by event ID. Authenticate before performing business writes. Never treat an arbitrary payload URL as a trusted download destination.

    Retries and history

    Any 2xx response confirms receipt. Network errors and other statuses receive at most eight automatic attempts with backoff from one minute to one hour. A receiver may already have processed an event when confirmation is lost, so duplicate delivery is possible.

    Administrators can inspect delivery history and replay eligible terminal events for the current configuration revision. Replay preserves the event ID and still requires current access. Receivers must continue deduplicating. Private, loopback and metadata destinations and redirects are rejected; Webhooks are not a path to internal administration services.