Interaction Best Practices

People expect an agent in Pulse to respond as part of the workflow they already use. The app should acknowledge a request, report meaningful progress, react to follow-ups and leave a result the human assignee can review.

Recommendations

When a created webhook arrives, verify its signature, record data.event_id and return 2xx within 5 seconds. Start the run in a background job. Post a short thought as the first activity so the person sees that the app received the request.

If the delegated issue is in backlog or todo, move it to in_progress when work begins. The app may later move it to qa, but cannot close it. Keep the human assignee informed and finish with a response that states what changed, what remains and what the person should review. The app cannot change its own delegation.

During a long run, send progress only when it adds useful information. Use an ephemeral thought or action for a temporary status; a later activity replaces it in the panel without erasing it from the activity history.

Agent activities

Issue comments can be edited after the app has read them. Agent activities preserve the prompts and answers as the session received them, with author, seq and timestamp. Reconstruct a conversation from GET /api/v1/agent-sessions/{session_id}/activities, then resume with after_seq rather than rereading comments.

Choose the activity that matches the moment: thought for acknowledgement, action for work done, elicitation for a question, response for the result and error for a blocker. Do not put credentials or private tool output in an activity: people who can read the issue may also read the session. Reuse a stable Idempotency-Key on retries.

Additional webhooks

The two core AgentSessionEvent actions cover a new request and a follow-up. Opt into additional resource events only when the app needs them. All deliveries are at least once, so deduplicate before taking action.

Issue and comment webhooks

Issue, Comment and Project events are optional in the app's resource_types. Use them when the app must react to changes outside an open session, such as an issue update or a new comment. They do not replace AgentSessionEvent for delegation, mentions or session replies. Pulse does not currently provide a separate inbox-notification webhook category for agent apps.

Permission change webhooks

PermissionChange / teamAccessChanged tells the app when the admin changes the installation's teams. Stop work on removed teams and update the app's local access map. Pulse releases their delegations and ends affected sessions with end_reason: team_removed.

{ "type": "PermissionChange", "action": "teamAccessChanged", "data": { "added_team_ids": [], "removed_team_ids": ["68da1fb8af973c6419b9b3f7"] } }

OAuthApp / revoked means the installation was removed. Discard its tokens and stop its jobs; the app can no longer post a final activity. See the full webhook envelopes.

Existing integrations

When to build an integration or agent

Use a regular integration when the connection primarily shares data with another service or acts on behalf of a signed-in person. Register an agent app when people should delegate an issue or @mention a distinct application user and follow its work in an agent session. The app's actions then carry its own identity and installation-scoped access.

Convert an existing integration

Pulse does not convert an installed integration into an agent app in place. Register a new agent app, add the OAuth redirect and signed webhook receiver, and let an admin install it. Migrate only the work and credentials the new app needs; do not reuse a person's access token as the app token. The getting started guide describes the installation path.

Feedback, requests, questions

Before inviting people to use the app, test installation, delegation, mention, the first activity, a long run, a follow-up, elicitation, Stop, team removal and uninstall. If a payload or behavior is unclear, record the event type, webhook_id and a redacted example so it can be investigated. Keep tokens and signing secrets out of reports. The API reference lists the exact payloads and error codes.