Chatwoot inboxes, integrations, and webhooks

Use these 21 capabilities to inspect and configure Chatwoot inboxes, membership, integration hooks, and account webhook records. Select the family that owns the provider object; similarly named operations do not configure the same boundary.

These capabilities call Chatwoot’s account API. They are separate from the connector host’s inbound /webhooks/chatwoot route, its HMAC secret, and its durable replay fence.

Family at a glance

All 21 capabilities are Tools. The seven GET operations are low-risk reads. Nine ordinary POST and PATCH operations are medium risk. The inbox.webhook.register operation and all four deletes are high risk.

All 14 mutations require approval and an idempotency key. None advertises connector retry support or compensation.

Choose the correct surface

Creating a provider webhook does not enable the connector-host ingress. The host route exists only when its owner supplies the webhook secret file and the required event-publication endpoint.

Inbox and member operations

The three member mutations use a collection route without an inbox_id path placeholder. Their provider body must identify the intended membership according to the pinned Chatwoot API. The generic AIP schema does not enforce that provider rule.

inbox.health reads provider state for one channel. It does not report connector-host readiness, registry admission, webhook replay storage, or event publication health.

Integration operations

The reviewed surface can list integration applications, but it cannot create, update, or delete an application. The three mutations operate only on integration hooks.

Account-webhook operations

These operations manage provider records. They do not write AIP_CHATWOOT_WEBHOOK_SECRET_FILE, create an AIP event-publication route, or prove that Chatwoot can reach the connector host.

Account and path inputs

The connector inserts its configured account_id into every path. Action input never selects the account.

Each path input is a non-blank string of at most 512 bytes and cannot contain a control character. The URL builder encodes each value as one path segment.

The common catalogue envelope also accepts:

• an optional query object with at most 128 keys;
• an optional body object with at most 512 properties and a 16 MiB encoded request limit;
• an optional bounded multipart object instead of body.

The connector rejects an input containing both body and multipart. It does not freeze provider-specific body fields for any of these 21 operations. Validate every body against the exact provider route and pinned Chatwoot revision before requesting approval.

Read inbox health

Use the inbox ID from an admitted provider record:

aipctl action call \
  "$AIP_URL" \
  cap:chatwoot:inbox.health \
  --action-id act_chatwoot_inbox_health_001 \
  --input '{"inbox_id":"7"}'

The connector calls:

GET /api/v1/accounts/{configured_account_id}/inboxes/7/health

The operation is a low-risk read and is safe to retry within the Action contract. Its provider body remains restricted data and may contain channel detail. Do not expose it merely because the operation needs no human approval.

Prepare a configuration mutation

The pinned Rust catalogue deliberately does not own provider payload fields. For webhook.create, integration.hook.create, or inbox.webhook.register, use this sequence:

1. Confirm that tenant discovery admits the exact capability.
2. Select the payload schema for the pinned Chatwoot route.
3. Build one bounded body object and retain its canonical form.
4. Bind approval to the exact capability, body, actor, tenant, and Action.
5. Assign one external-account-scoped idempotency key.
6. Dispatch the Action once.
7. Verify provider state with the corresponding read when one exists.

No copy-ready provider body appears here because the connector source does not validate one. Adding guessed URL, subscription, or integration fields would turn a source-backed reference into an unpinned provider example.

inbox.webhook.register is high risk even though it uses POST. Treat the destination and resulting delivery path as security-sensitive configuration. Approval does not prove endpoint ownership, reachability, or signature compatibility.

Keep provider management and inbound delivery separate

Omitting the webhook secret file creates an outbound-only host and no Chatwoot webhook route. Supplying the file also requires the connector-host event endpoint; startup rejects the incomplete ingress configuration.

Detailed signature construction, required headers, replay behavior, loop prevention, and delivery errors belong to webhook-security-loop-prevention-and-replay.md later in this connector section.

Shared mutation contract

All 14 mutations declare:

Provider configuration may cause later network traffic or automated behavior, but the generic contracts do not enumerate those downstream effects. Policy must consider the selected operation and body, not only the two generic side-effect markers.

Result contract

Every successful catalogue operation returns:

{
  "http_status": 200,
  "body": {},
  "provider_request_id": null
}

body contains parsed provider JSON, null for an empty response, or a text wrapper for a non-JSON response. provider_request_id takes the x-request-id header first and x-runtime second.

The output schema does not define provider webhook, inbox, or integration fields. Validate the shape needed by the application and retain unknown fields for compatibility.

Failures and recovery

All connector failures advertise retryable: false. The seven read contracts separately allow a bounded retry. Mutations remain unsafe to repeat even when they carry an idempotency key.

After an uncertain provider-configuration mutation, inspect Chatwoot before creating another Action. A lost response can hide a successfully created hook or inbox. Repeating it with a new identity can create duplicate delivery paths.

Verify an integration

Require all of the following:

• the selected capability matches the provider object being managed;
• discovery admits the exact suffix for the intended account route;
• no caller-selected account ID crosses the host boundary;
• path IDs and provider body come from authoritative state;
• every mutation has exact approval evidence and one retained idempotency key;
• a provider read confirms the resulting record when available;
• connector-host ingress is configured and verified independently;
• restricted payloads, destinations, tokens, and event data are redacted;
• uncertain mutations are reconciled instead of repeated.

These checks validate application handling. They do not prove provider delivery, inbound signature compatibility, or live qualification.

Related documentation

• Chatwoot capability index
• Chatwoot connector overview
• Chatwoot connector configuration
• Authentication and account isolation
• Approvals and policy