Webhooks and events
Which provider events Watari subscribes to, how retries and signed payloads work, and what happens when a delivery fails.
An overview of the event surface Watari sits on, what it listens to and what it sends out.
Incoming webhooks: what Watari receives
Watari subscribes to events from five external systems. Every inbound webhook is verified on receipt: Zendesk, Intercom, GitHub, and Razorpay against their HMAC signature, and Freshdesk against a per-tenant secret token (Freshdesk has no signed-webhook product). Payloads that fail verification are rejected with a single 401 response and are never retried by Watari.
Zendesk
Watari registers its own webhook on your Zendesk account during the OAuth flow. Events received:
- Ticket created: triggers extraction.
- Ticket updated (customer reply added, status changed), re-queues extraction if the update contains new customer content.
Intercom
Watari subscribes to conversation events on your workspace during OAuth. Events received:
- Conversation created: triggers extraction.
- Conversation part added (customer message or teammate message), re-queues extraction on new customer content.
Freshdesk
Freshdesk has no OAuth or auto-registered webhooks, so you wire one Automation Rule that posts to Watari when an agent escalates a ticket (moves it into your Engineering group, or sets the Type). The request carries a per-tenant secret token in a header, which Watari verifies. Events received:
- Ticket escalated (group or type changed by an agent), triggers extraction. Watari re-fetches the full ticket from Freshdesk's API rather than trusting the webhook body.
GitHub
The GitHub App subscription covers the events needed for code mapping, PR lifecycle, CI status, and deploy detection. Key subscriptions:
| Event | Why Watari uses it |
|---|---|
push | Incremental reindex when your default branch changes |
pull_request | Detect PR merge or close; kick off RCA flow |
pull_request_review | Reviewer comment iteration, triggers re-generation |
issue_comment | Reviewer comment iteration via issue-thread comments on PRs, and a mention of Watari in a comment on an issue when issue pickup is on |
issues | Picking up the issues you hand to Watari (a label, a mention, an assignment, or every new issue), only when you have turned issue pickup on and only in the repositories you chose. Issue events from any other repository are discarded on arrival and nothing from them is kept |
check_run / check_suite | CI status on the PR, and the fix for failing CI on Watari's draft PRs |
status | Legacy commit-status from CI providers that don't use Checks API |
deployment_status | Production deploy detection: triggers RCA publish when configured (works for platforms that report deployments to GitHub: Vercel, Netlify, Render, and most CD platforms; environment match is case-insensitive) |
installation | App lifecycle (install, uninstall, suspend) |
Linear
Once Linear is connected, Linear notifies Watari when an issue in your workspace is created or changed, and when someone delegates an issue to Watari or mentions it. Each notice is signed by Linear, and Watari checks the signature before reading it. Events received:
- Issue created or changed: read only when Watari is installed as an app in your Linear workspace, issue pickup is on, and the issue is in a team you chose. Every other issue notice is discarded on arrival and nothing from it is kept.
- Issue delegated to Watari, or Watari mentioned: Watari replies on the issue and, when pickup is on for that team, picks it up.
- Watari removed from your workspace: the Linear card shows that a reconnect is needed.
Watari does not receive your Linear comments, apart from the one comment in which someone mentions it.
Razorpay
Watari receives subscription lifecycle events from Razorpay. These drive billing state: activating subscriptions, handling payment failures, advancing dunning states, and triggering the monthly overage invoice close.
What triggers the Watari pipeline
Not every inbound event starts full processing. The events that trigger the ticket-to-bug pipeline are:
- A new Zendesk ticket, Intercom conversation, or escalated Freshdesk ticket arrives.
- A Zendesk ticket or Intercom conversation receives a new customer reply (existing ticket, new content).
- A GitHub, Jira or Linear issue, or an Azure Boards work item, is handed to Watari, in a repository, project or team where you turned pickup on.
- A GitHub PR review comment is left on a Watari-drafted PR (triggers PR iteration).
- A CI result lands on a Watari-drafted PR (a code failure on Watari's own commit triggers a fix commit, unless you turned it off).
- A GitHub deployment_status event arrives for a production environment (triggers RCA publish, if configured).
Outbound events: what Watari sends
Watari posts to connected destinations as an issue moves.
| Destination | When Watari posts |
|---|---|
| Slack | One card per issue, edited in place as the issue moves and shrunk to one line when it is done, plus usage and waiting-too-long alerts |
| Microsoft Teams | The same issue cards as Adaptive Cards posted to your Teams workflow. Teams cannot edit a card, so after the first card a new one is posted only when the issue becomes your move or is done |
| Linear | A new issue filed in your team. On an issue Watari picked up: a reply when it is delegated or mentioned, progress comments, the draft fix attached as a link, and the customer update as a comment after the fix ships, on an issue read only inside your workspace |
| Jira | A new issue filed in your project (a Bug, or the nearest type your project has; for a feature request, a Story or the nearest type). On an issue Watari picked up: progress comments, and, on an issue only your team can see, the draft fix added as a web link and the customer update as a comment after the fix ships |
| GitHub | Draft fix opened as a draft pull request, review requests sent, replies to review comments with follow-up fixes. On an issue Watari picked up: progress comments, a "Source issue" comment on the draft fix, and the customer update as a comment after the fix ships when the repository is private |
| Zendesk | Customer update posted as a public ticket comment after the fix ships |
| Intercom | Customer update posted as a conversation reply after the fix ships |
| Freshdesk | Customer update posted as a public ticket reply after the fix ships |
| Azure Boards | Progress comments on a work item Watari picked up, and the customer update as a comment after the fix ships |
Progress comments on a tracker open with Your move and the next step whenever a person needs to act, and never carry scores or file paths. See What Watari's comments say.
Watari does not currently provide a customer-facing webhook subscription API. If you need to receive Watari events in your own systems (for example, to sync Mapped Issues into an internal tool) contact us at /contact. Outbound webhook subscriptions are on the roadmap.
Retry behavior
Failed outbound deliveries. When Watari posts to Slack, Linear, or Jira and the request fails, it retries with exponential backoff. Watari retries automatically; the limit is not configurable.
Slack channel errors. If Slack returns a channel-gone error (channel_not_found, is_archived, not_in_channel), Watari stops posting to that channel and marks the integration as errored rather than retrying indefinitely. A monthly background job rechecks errored integrations and recovers automatically if the channel is available again. See Routing and notifications, Slack channel-invite step for the invite-bot step that prevents the most common cause of this.
Linear and Jira delivery failures. If issue creation fails for Linear or Jira (expired token, project permissions changed, API error) the failure appears on the issue page as a delivery error. Reconnect the integration from Settings → Connected tools to resume.
Inbound verification failures. A webhook that fails verification gets a single 401 response. Watari does not retry from its side: the sending system (Zendesk, Intercom, Freshdesk, GitHub, Razorpay) will retry according to its own retry policy if it receives a non-2xx response.
Next: Disconnecting integrations: token revocation and data retention windows: token revocation, what data persists after disconnect, and full deletion.
Microsoft Teams app
Add the Watari app to a Teams team, connect it to your workspace, choose the channel, and act on issue cards without leaving Teams. Covers who can press what, disconnecting, and the Teams workflow option that works today.
Disconnecting and data handling
What happens when you disconnect an integration: token revocation, retention windows, and full deletion.