{
  "schemaVersion": "1.0",
  "title": "Chatwoot inboxes, integrations, and webhooks",
  "description": "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.",
  "canonical": "https://getaip.org/docs/connectors/chatwoot/capabilities/inboxes-integrations-and-webhooks",
  "route": "/docs/connectors/chatwoot/capabilities/inboxes-integrations-and-webhooks",
  "source": "docs/connectors/chatwoot/capabilities/inboxes-integrations-and-webhooks.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/chatwoot/capabilities/inboxes-integrations-and-webhooks.md",
    "txt": "/docs/download/connectors/chatwoot/capabilities/inboxes-integrations-and-webhooks.txt",
    "json": "/docs/download/connectors/chatwoot/capabilities/inboxes-integrations-and-webhooks.json",
    "pdf": "/docs/download/connectors/chatwoot/capabilities/inboxes-integrations-and-webhooks.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Chatwoot inboxes, integrations, and webhooks\ndescription: >-\n  Configure Chatwoot channels and provider hooks through 21 exact capabilities\n  without confusing them with the connector's inbound webhook security\nkind: capability-reference\naudience: application-developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: chatwoot\ncapabilityIds:\n  - cap:chatwoot:inbox.list\n  - cap:chatwoot:inbox.create\n  - cap:chatwoot:inbox.get\n  - cap:chatwoot:inbox.update\n  - cap:chatwoot:inbox.delete\n  - cap:chatwoot:inbox.agent.list\n  - cap:chatwoot:inbox.health\n  - cap:chatwoot:inbox.template.sync\n  - cap:chatwoot:inbox.webhook.register\n  - cap:chatwoot:inbox.member.list\n  - cap:chatwoot:inbox.member.create\n  - cap:chatwoot:inbox.member.update\n  - cap:chatwoot:inbox.member.delete\n  - cap:chatwoot:integration.app.list\n  - cap:chatwoot:integration.hook.create\n  - cap:chatwoot:integration.hook.update\n  - cap:chatwoot:integration.hook.delete\n  - cap:chatwoot:webhook.list\n  - cap:chatwoot:webhook.create\n  - cap:chatwoot:webhook.update\n  - cap:chatwoot:webhook.delete\naliases:\n  - Chatwoot channel capabilities\n  - Chatwoot webhook management\n---\n\n# Chatwoot inboxes, integrations, and webhooks\n\nUse these 21 capabilities to inspect and configure Chatwoot inboxes,\nmembership, integration hooks, and account webhook records. Select the family\nthat owns the provider object; similarly named operations do not configure the\nsame boundary.\n\nThese capabilities call Chatwoot's account API. They are separate from the\nconnector host's inbound `/webhooks/chatwoot` route, its HMAC secret, and its\ndurable replay fence.\n\n## Family at a glance\n\n| Group | Operations | Reads | Mutations | High risk |\n|---|---:|---:|---:|---:|\n| Inboxes and members | 13 | 5 | 8 | 3 |\n| Integration apps and hooks | 4 | 1 | 3 | 1 |\n| Account webhooks | 4 | 1 | 3 | 1 |\n| **Total** | **21** | **7** | **14** | **5** |\n\nAll 21 capabilities are Tools. The seven `GET` operations are low-risk reads.\nNine ordinary `POST` and `PATCH` operations are medium risk. The\n`inbox.webhook.register` operation and all four deletes are high risk.\n\nAll 14 mutations require approval and an idempotency key. None advertises\nconnector retry support or compensation.\n\n## Choose the correct surface\n\n| Task | Capability group | Boundary |\n|---|---|---|\n| Inspect or configure a channel | `inbox.*` | Inbox object in the configured account |\n| Read or replace inbox membership | `inbox.member.*` | Provider inbox-member collection |\n| Inspect provider integration applications | `integration.app.list` | Account integration-app inventory |\n| Create, update, or remove an integration hook | `integration.hook.*` | Provider integration hook |\n| Create, update, or remove an account webhook | `webhook.*` | Provider account-webhook object |\n| Register the provider webhook for one inbox | `inbox.webhook.register` | Special high-risk inbox operation |\n| Receive a signed delivery in AIP | Not an Action capability | Connector-host webhook ingress |\n\nCreating a provider webhook does not enable the connector-host ingress. The\nhost route exists only when its owner supplies the webhook secret file and the\nrequired event-publication endpoint.\n\n## Inbox and member operations\n\n| Capability | Provider request | Purpose | Risk | Approval |\n|---|---|---|---|---|\n| `cap:chatwoot:inbox.list` | `GET /api/v1/accounts/{account_id}/inboxes` | List inboxes | Low | No |\n| `cap:chatwoot:inbox.create` | `POST /api/v1/accounts/{account_id}/inboxes` | Create an inbox | Medium | Required |\n| `cap:chatwoot:inbox.get` | `GET /api/v1/accounts/{account_id}/inboxes/{inbox_id}` | Read one inbox | Low | No |\n| `cap:chatwoot:inbox.update` | `PATCH /api/v1/accounts/{account_id}/inboxes/{inbox_id}` | Update one inbox | Medium | Required |\n| `cap:chatwoot:inbox.delete` | `DELETE /api/v1/accounts/{account_id}/inboxes/{inbox_id}` | Delete one inbox | High | Required |\n| `cap:chatwoot:inbox.agent.list` | `GET /api/v1/accounts/{account_id}/inboxes/{inbox_id}/assignable_agents` | List assignable agents | Low | No |\n| `cap:chatwoot:inbox.health` | `GET /api/v1/accounts/{account_id}/inboxes/{inbox_id}/health` | Read provider inbox health | Low | No |\n| `cap:chatwoot:inbox.template.sync` | `POST /api/v1/accounts/{account_id}/inboxes/{inbox_id}/sync_templates` | Synchronize inbox templates | Medium | Required |\n| `cap:chatwoot:inbox.webhook.register` | `POST /api/v1/accounts/{account_id}/inboxes/{inbox_id}/register_webhook` | Register the provider webhook for an inbox | High | Required |\n| `cap:chatwoot:inbox.member.list` | `GET /api/v1/accounts/{account_id}/inbox_members/{inbox_id}` | Read inbox members | Low | No |\n| `cap:chatwoot:inbox.member.create` | `POST /api/v1/accounts/{account_id}/inbox_members` | Add inbox members | Medium | Required |\n| `cap:chatwoot:inbox.member.update` | `PATCH /api/v1/accounts/{account_id}/inbox_members` | Replace inbox members | Medium | Required |\n| `cap:chatwoot:inbox.member.delete` | `DELETE /api/v1/accounts/{account_id}/inbox_members` | Remove inbox members | High | Required |\n\nThe three member mutations use a collection route without an `inbox_id` path\nplaceholder. Their provider body must identify the intended membership\naccording to the pinned Chatwoot API. The generic AIP schema does not enforce\nthat provider rule.\n\n`inbox.health` reads provider state for one channel. It does not report\nconnector-host readiness, registry admission, webhook replay storage, or event\npublication health.\n\n## Integration operations\n\n| Capability | Provider request | Purpose | Risk | Approval |\n|---|---|---|---|---|\n| `cap:chatwoot:integration.app.list` | `GET /api/v1/accounts/{account_id}/integrations/apps` | List integration applications | Low | No |\n| `cap:chatwoot:integration.hook.create` | `POST /api/v1/accounts/{account_id}/integrations/hooks` | Create an integration hook | Medium | Required |\n| `cap:chatwoot:integration.hook.update` | `PATCH /api/v1/accounts/{account_id}/integrations/hooks/{hook_id}` | Update one integration hook | Medium | Required |\n| `cap:chatwoot:integration.hook.delete` | `DELETE /api/v1/accounts/{account_id}/integrations/hooks/{hook_id}` | Delete one integration hook | High | Required |\n\nThe reviewed surface can list integration applications, but it cannot create,\nupdate, or delete an application. The three mutations operate only on\nintegration hooks.\n\n## Account-webhook operations\n\n| Capability | Provider request | Purpose | Risk | Approval |\n|---|---|---|---|---|\n| `cap:chatwoot:webhook.list` | `GET /api/v1/accounts/{account_id}/webhooks` | List account webhooks | Low | No |\n| `cap:chatwoot:webhook.create` | `POST /api/v1/accounts/{account_id}/webhooks` | Create an account webhook | Medium | Required |\n| `cap:chatwoot:webhook.update` | `PATCH /api/v1/accounts/{account_id}/webhooks/{webhook_id}` | Update one account webhook | Medium | Required |\n| `cap:chatwoot:webhook.delete` | `DELETE /api/v1/accounts/{account_id}/webhooks/{webhook_id}` | Delete one account webhook | High | Required |\n\nThese operations manage provider records. They do not write\n`AIP_CHATWOOT_WEBHOOK_SECRET_FILE`, create an AIP event-publication route, or\nprove that Chatwoot can reach the connector host.\n\n## Account and path inputs\n\nThe connector inserts its configured `account_id` into every path. Action\ninput never selects the account.\n\n| Input | Required by |\n|---|---|\n| `inbox_id` | `inbox.get`, `inbox.update`, `inbox.delete`, `inbox.agent.list`, `inbox.health`, `inbox.template.sync`, `inbox.webhook.register`, and `inbox.member.list` |\n| `hook_id` | `integration.hook.update` and `integration.hook.delete` |\n| `webhook_id` | `webhook.update` and `webhook.delete` |\n\nEach path input is a non-blank string of at most 512 bytes and cannot contain a\ncontrol character. The URL builder encodes each value as one path segment.\n\nThe common catalogue envelope also accepts:\n\n- an optional `query` object with at most 128 keys;\n- an optional `body` object with at most 512 properties and a 16 MiB encoded\n  request limit;\n- an optional bounded `multipart` object instead of `body`.\n\nThe connector rejects an input containing both `body` and `multipart`. It does\nnot freeze provider-specific body fields for any of these 21 operations.\nValidate every body against the exact provider route and pinned Chatwoot\nrevision before requesting approval.\n\n## Read inbox health\n\nUse the inbox ID from an admitted provider record:\n\n```sh\naipctl action call \\\n  \"$AIP_URL\" \\\n  cap:chatwoot:inbox.health \\\n  --action-id act_chatwoot_inbox_health_001 \\\n  --input '{\"inbox_id\":\"7\"}'\n```\n\nThe connector calls:\n\n```text\nGET /api/v1/accounts/{configured_account_id}/inboxes/7/health\n```\n\nThe operation is a low-risk read and is safe to retry within the Action\ncontract. Its provider body remains restricted data and may contain channel\ndetail. Do not expose it merely because the operation needs no human approval.\n\n## Prepare a configuration mutation\n\nThe pinned Rust catalogue deliberately does not own provider payload fields.\nFor `webhook.create`, `integration.hook.create`, or\n`inbox.webhook.register`, use this sequence:\n\n1. Confirm that tenant discovery admits the exact capability.\n2. Select the payload schema for the pinned Chatwoot route.\n3. Build one bounded `body` object and retain its canonical form.\n4. Bind approval to the exact capability, body, actor, tenant, and Action.\n5. Assign one external-account-scoped idempotency key.\n6. Dispatch the Action once.\n7. Verify provider state with the corresponding read when one exists.\n\nNo copy-ready provider body appears here because the connector source does not\nvalidate one. Adding guessed URL, subscription, or integration fields would\nturn a source-backed reference into an unpinned provider example.\n\n`inbox.webhook.register` is high risk even though it uses `POST`. Treat the\ndestination and resulting delivery path as security-sensitive configuration.\nApproval does not prove endpoint ownership, reachability, or signature\ncompatibility.\n\n## Keep provider management and inbound delivery separate\n\n| Boundary | Owned by | Source-visible control |\n|---|---|---|\n| Provider webhook or integration record | A Chatwoot capability | Approved provider mutation |\n| Connector inbound route | `aip-host-chatwoot` | `POST /webhooks/chatwoot` |\n| Inbound HMAC material | Connector host operator | Owner-only webhook secret file |\n| Delivery freshness and replay | Connector runtime | 300-second timestamp window and durable instance-scoped replay state |\n| Event publication | Connector host and runtime | Configured connector-host event endpoint and durable outbox |\n| Loop prevention | Connector mapping | AIP content attributes on connector-originated messages |\n\nOmitting the webhook secret file creates an outbound-only host and no Chatwoot\nwebhook route. Supplying the file also requires the connector-host event\nendpoint; startup rejects the incomplete ingress configuration.\n\nDetailed signature construction, required headers, replay behavior, loop\nprevention, and delivery errors belong to\n`webhook-security-loop-prevention-and-replay.md` later in this connector\nsection.\n\n## Shared mutation contract\n\nAll 14 mutations declare:\n\n| Contract field | Value |\n|---|---|\n| Approval | Required; tenant-policy selector |\n| Approval validity | 900,000 ms |\n| Approval evidence | Reason, input snapshot, policy decision |\n| Idempotency | Required; external-account scope; 86,400,000 ms published TTL |\n| Retry | Not supported; unsafe |\n| Side effects | `write`, `external_network` |\n| Data | Restricted; contains PII; redaction required |\n| Execution | Synchronous; no async, streaming, or cancellation support |\n| Compensation | Rollback not supported |\n\nProvider configuration may cause later network traffic or automated behavior,\nbut the generic contracts do not enumerate those downstream effects. Policy\nmust consider the selected operation and body, not only the two generic\nside-effect markers.\n\n## Result contract\n\nEvery successful catalogue operation returns:\n\n```json\n{\n  \"http_status\": 200,\n  \"body\": {},\n  \"provider_request_id\": null\n}\n```\n\n`body` contains parsed provider JSON, `null` for an empty response, or a\n`text` wrapper for a non-JSON response. `provider_request_id` takes the\n`x-request-id` header first and `x-runtime` second.\n\nThe output schema does not define provider webhook, inbox, or integration\nfields. Validate the shape needed by the application and retain unknown fields\nfor compatibility.\n\n## Failures and recovery\n\n| Failure code | Typical cause | Safe response |\n|---|---|---|\n| `connector.chatwoot.invalid_action` | Unknown or unadmitted operation, missing path input, or malformed generic envelope | Refresh discovery or correct input before dispatch |\n| `connector.chatwoot.missing_idempotency_key` | Mutation has no valid key | Restore the key bound to the same canonical intent |\n| `connector.chatwoot.authentication` | Provider returned `401` or `403` | Verify account binding and credential revision |\n| `connector.chatwoot.remote_rejected` | Provider rejected the body or current state | Correct the payload or provider state before a new Action |\n| `connector.chatwoot.remote_temporary` | Provider returned `429` or a server error | Retry a read within policy; reconcile a mutation |\n| `connector.chatwoot.transport` | Provider exchange failed | Retry a read within policy; treat mutation outcome as uncertain |\n| `connector.chatwoot.response_too_large` | Response crossed the configured bound | Inspect provider output and reconcile a mutation |\n\nAll connector failures advertise `retryable: false`. The seven read contracts\nseparately allow a bounded retry. Mutations remain unsafe to repeat even when\nthey carry an idempotency key.\n\nAfter an uncertain provider-configuration mutation, inspect Chatwoot before\ncreating another Action. A lost response can hide a successfully created hook\nor inbox. Repeating it with a new identity can create duplicate delivery paths.\n\n## Verify an integration\n\nRequire all of the following:\n\n- the selected capability matches the provider object being managed;\n- discovery admits the exact suffix for the intended account route;\n- no caller-selected account ID crosses the host boundary;\n- path IDs and provider body come from authoritative state;\n- every mutation has exact approval evidence and one retained idempotency key;\n- a provider read confirms the resulting record when available;\n- connector-host ingress is configured and verified independently;\n- restricted payloads, destinations, tokens, and event data are redacted;\n- uncertain mutations are reconciled instead of repeated.\n\nThese checks validate application handling. They do not prove provider\ndelivery, inbound signature compatibility, or live qualification.\n\n## Related documentation\n\n- [Chatwoot capability index](README.md)\n- [Chatwoot connector overview](../README.md)\n- [Chatwoot connector configuration](../reference/configuration.md)\n- [Authentication and account isolation](../getting-started/authentication-and-account-isolation.md)\n- [Approvals and policy](../../../concepts/approvals-and-policy.md)\n",
    "text": "Chatwoot inboxes, integrations, and webhooks\n\nUse these 21 capabilities to inspect and configure Chatwoot inboxes,\nmembership, integration hooks, and account webhook records. Select the family\nthat owns the provider object; similarly named operations do not configure the\nsame boundary.\n\nThese capabilities call Chatwoot's account API. They are separate from the\nconnector host's inbound /webhooks/chatwoot route, its HMAC secret, and its\ndurable replay fence.\n\nFamily at a glance\n\n| Group | Operations | Reads | Mutations | High risk |\n\n| Inboxes and members | 13 | 5 | 8 | 3 |\n| Integration apps and hooks | 4 | 1 | 3 | 1 |\n| Account webhooks | 4 | 1 | 3 | 1 |\n| Total | 21 | 7 | 14 | 5 |\n\nAll 21 capabilities are Tools. The seven GET operations are low-risk reads.\nNine ordinary POST and PATCH operations are medium risk. The\ninbox.webhook.register operation and all four deletes are high risk.\n\nAll 14 mutations require approval and an idempotency key. None advertises\nconnector retry support or compensation.\n\nChoose the correct surface\n\n| Task | Capability group | Boundary |\n\n| Inspect or configure a channel | inbox. | Inbox object in the configured account |\n| Read or replace inbox membership | inbox.member. | Provider inbox-member collection |\n| Inspect provider integration applications | integration.app.list | Account integration-app inventory |\n| Create, update, or remove an integration hook | integration.hook. | Provider integration hook |\n| Create, update, or remove an account webhook | webhook. | Provider account-webhook object |\n| Register the provider webhook for one inbox | inbox.webhook.register | Special high-risk inbox operation |\n| Receive a signed delivery in AIP | Not an Action capability | Connector-host webhook ingress |\n\nCreating a provider webhook does not enable the connector-host ingress. The\nhost route exists only when its owner supplies the webhook secret file and the\nrequired event-publication endpoint.\n\nInbox and member operations\n\n| Capability | Provider request | Purpose | Risk | Approval |\n\n| cap:chatwoot:inbox.list | GET /api/v1/accounts/{accountid}/inboxes | List inboxes | Low | No |\n| cap:chatwoot:inbox.create | POST /api/v1/accounts/{accountid}/inboxes | Create an inbox | Medium | Required |\n| cap:chatwoot:inbox.get | GET /api/v1/accounts/{accountid}/inboxes/{inboxid} | Read one inbox | Low | No |\n| cap:chatwoot:inbox.update | PATCH /api/v1/accounts/{accountid}/inboxes/{inboxid} | Update one inbox | Medium | Required |\n| cap:chatwoot:inbox.delete | DELETE /api/v1/accounts/{accountid}/inboxes/{inboxid} | Delete one inbox | High | Required |\n| cap:chatwoot:inbox.agent.list | GET /api/v1/accounts/{accountid}/inboxes/{inboxid}/assignableagents | List assignable agents | Low | No |\n| cap:chatwoot:inbox.health | GET /api/v1/accounts/{accountid}/inboxes/{inboxid}/health | Read provider inbox health | Low | No |\n| cap:chatwoot:inbox.template.sync | POST /api/v1/accounts/{accountid}/inboxes/{inboxid}/synctemplates | Synchronize inbox templates | Medium | Required |\n| cap:chatwoot:inbox.webhook.register | POST /api/v1/accounts/{accountid}/inboxes/{inboxid}/registerwebhook | Register the provider webhook for an inbox | High | Required |\n| cap:chatwoot:inbox.member.list | GET /api/v1/accounts/{accountid}/inboxmembers/{inboxid} | Read inbox members | Low | No |\n| cap:chatwoot:inbox.member.create | POST /api/v1/accounts/{accountid}/inboxmembers | Add inbox members | Medium | Required |\n| cap:chatwoot:inbox.member.update | PATCH /api/v1/accounts/{accountid}/inboxmembers | Replace inbox members | Medium | Required |\n| cap:chatwoot:inbox.member.delete | DELETE /api/v1/accounts/{accountid}/inboxmembers | Remove inbox members | High | Required |\n\nThe three member mutations use a collection route without an inboxid path\nplaceholder. Their provider body must identify the intended membership\naccording to the pinned Chatwoot API. The generic AIP schema does not enforce\nthat provider rule.\n\ninbox.health reads provider state for one channel. It does not report\nconnector-host readiness, registry admission, webhook replay storage, or event\npublication health.\n\nIntegration operations\n\n| Capability | Provider request | Purpose | Risk | Approval |\n\n| cap:chatwoot:integration.app.list | GET /api/v1/accounts/{accountid}/integrations/apps | List integration applications | Low | No |\n| cap:chatwoot:integration.hook.create | POST /api/v1/accounts/{accountid}/integrations/hooks | Create an integration hook | Medium | Required |\n| cap:chatwoot:integration.hook.update | PATCH /api/v1/accounts/{accountid}/integrations/hooks/{hookid} | Update one integration hook | Medium | Required |\n| cap:chatwoot:integration.hook.delete | DELETE /api/v1/accounts/{accountid}/integrations/hooks/{hookid} | Delete one integration hook | High | Required |\n\nThe reviewed surface can list integration applications, but it cannot create,\nupdate, or delete an application. The three mutations operate only on\nintegration hooks.\n\nAccount-webhook operations\n\n| Capability | Provider request | Purpose | Risk | Approval |\n\n| cap:chatwoot:webhook.list | GET /api/v1/accounts/{accountid}/webhooks | List account webhooks | Low | No |\n| cap:chatwoot:webhook.create | POST /api/v1/accounts/{accountid}/webhooks | Create an account webhook | Medium | Required |\n| cap:chatwoot:webhook.update | PATCH /api/v1/accounts/{accountid}/webhooks/{webhookid} | Update one account webhook | Medium | Required |\n| cap:chatwoot:webhook.delete | DELETE /api/v1/accounts/{accountid}/webhooks/{webhookid} | Delete one account webhook | High | Required |\n\nThese operations manage provider records. They do not write\nAIPCHATWOOTWEBHOOKSECRETFILE, create an AIP event-publication route, or\nprove that Chatwoot can reach the connector host.\n\nAccount and path inputs\n\nThe connector inserts its configured accountid into every path. Action\ninput never selects the account.\n\n| Input | Required by |\n\n| inboxid | inbox.get, inbox.update, inbox.delete, inbox.agent.list, inbox.health, inbox.template.sync, inbox.webhook.register, and inbox.member.list |\n| hookid | integration.hook.update and integration.hook.delete |\n| webhookid | webhook.update and webhook.delete |\n\nEach path input is a non-blank string of at most 512 bytes and cannot contain a\ncontrol character. The URL builder encodes each value as one path segment.\n\nThe common catalogue envelope also accepts:\n• an optional query object with at most 128 keys;\n• an optional body object with at most 512 properties and a 16 MiB encoded\n  request limit;\n• an optional bounded multipart object instead of body.\n\nThe connector rejects an input containing both body and multipart. It does\nnot freeze provider-specific body fields for any of these 21 operations.\nValidate every body against the exact provider route and pinned Chatwoot\nrevision before requesting approval.\n\nRead inbox health\n\nUse the inbox ID from an admitted provider record:\n\naipctl action call \\\n  \"$AIPURL\" \\\n  cap:chatwoot:inbox.health \\\n  --action-id actchatwootinboxhealth001 \\\n  --input '{\"inboxid\":\"7\"}'\n\nThe connector calls:\n\nGET /api/v1/accounts/{configuredaccountid}/inboxes/7/health\n\nThe operation is a low-risk read and is safe to retry within the Action\ncontract. Its provider body remains restricted data and may contain channel\ndetail. Do not expose it merely because the operation needs no human approval.\n\nPrepare a configuration mutation\n\nThe pinned Rust catalogue deliberately does not own provider payload fields.\nFor webhook.create, integration.hook.create, or\ninbox.webhook.register, use this sequence:\n1. Confirm that tenant discovery admits the exact capability.\n2. Select the payload schema for the pinned Chatwoot route.\n3. Build one bounded body object and retain its canonical form.\n4. Bind approval to the exact capability, body, actor, tenant, and Action.\n5. Assign one external-account-scoped idempotency key.\n6. Dispatch the Action once.\n7. Verify provider state with the corresponding read when one exists.\n\nNo copy-ready provider body appears here because the connector source does not\nvalidate one. Adding guessed URL, subscription, or integration fields would\nturn a source-backed reference into an unpinned provider example.\n\ninbox.webhook.register is high risk even though it uses POST. Treat the\ndestination and resulting delivery path as security-sensitive configuration.\nApproval does not prove endpoint ownership, reachability, or signature\ncompatibility.\n\nKeep provider management and inbound delivery separate\n\n| Boundary | Owned by | Source-visible control |\n\n| Provider webhook or integration record | A Chatwoot capability | Approved provider mutation |\n| Connector inbound route | aip-host-chatwoot | POST /webhooks/chatwoot |\n| Inbound HMAC material | Connector host operator | Owner-only webhook secret file |\n| Delivery freshness and replay | Connector runtime | 300-second timestamp window and durable instance-scoped replay state |\n| Event publication | Connector host and runtime | Configured connector-host event endpoint and durable outbox |\n| Loop prevention | Connector mapping | AIP content attributes on connector-originated messages |\n\nOmitting the webhook secret file creates an outbound-only host and no Chatwoot\nwebhook route. Supplying the file also requires the connector-host event\nendpoint; startup rejects the incomplete ingress configuration.\n\nDetailed signature construction, required headers, replay behavior, loop\nprevention, and delivery errors belong to\nwebhook-security-loop-prevention-and-replay.md later in this connector\nsection.\n\nShared mutation contract\n\nAll 14 mutations declare:\n\n| Contract field | Value |\n\n| Approval | Required; tenant-policy selector |\n| Approval validity | 900,000 ms |\n| Approval evidence | Reason, input snapshot, policy decision |\n| Idempotency | Required; external-account scope; 86,400,000 ms published TTL |\n| Retry | Not supported; unsafe |\n| Side effects | write, externalnetwork |\n| Data | Restricted; contains PII; redaction required |\n| Execution | Synchronous; no async, streaming, or cancellation support |\n| Compensation | Rollback not supported |\n\nProvider configuration may cause later network traffic or automated behavior,\nbut the generic contracts do not enumerate those downstream effects. Policy\nmust consider the selected operation and body, not only the two generic\nside-effect markers.\n\nResult contract\n\nEvery successful catalogue operation returns:\n\n{\n  \"httpstatus\": 200,\n  \"body\": {},\n  \"providerrequestid\": null\n}\n\nbody contains parsed provider JSON, null for an empty response, or a\ntext wrapper for a non-JSON response. providerrequestid takes the\nx-request-id header first and x-runtime second.\n\nThe output schema does not define provider webhook, inbox, or integration\nfields. Validate the shape needed by the application and retain unknown fields\nfor compatibility.\n\nFailures and recovery\n\n| Failure code | Typical cause | Safe response |\n\n| connector.chatwoot.invalidaction | Unknown or unadmitted operation, missing path input, or malformed generic envelope | Refresh discovery or correct input before dispatch |\n| connector.chatwoot.missingidempotencykey | Mutation has no valid key | Restore the key bound to the same canonical intent |\n| connector.chatwoot.authentication | Provider returned 401 or 403 | Verify account binding and credential revision |\n| connector.chatwoot.remoterejected | Provider rejected the body or current state | Correct the payload or provider state before a new Action |\n| connector.chatwoot.remotetemporary | Provider returned 429 or a server error | Retry a read within policy; reconcile a mutation |\n| connector.chatwoot.transport | Provider exchange failed | Retry a read within policy; treat mutation outcome as uncertain |\n| connector.chatwoot.responsetoolarge | Response crossed the configured bound | Inspect provider output and reconcile a mutation |\n\nAll connector failures advertise retryable: false. The seven read contracts\nseparately allow a bounded retry. Mutations remain unsafe to repeat even when\nthey carry an idempotency key.\n\nAfter an uncertain provider-configuration mutation, inspect Chatwoot before\ncreating another Action. A lost response can hide a successfully created hook\nor inbox. Repeating it with a new identity can create duplicate delivery paths.\n\nVerify an integration\n\nRequire all of the following:\n• the selected capability matches the provider object being managed;\n• discovery admits the exact suffix for the intended account route;\n• no caller-selected account ID crosses the host boundary;\n• path IDs and provider body come from authoritative state;\n• every mutation has exact approval evidence and one retained idempotency key;\n• a provider read confirms the resulting record when available;\n• connector-host ingress is configured and verified independently;\n• restricted payloads, destinations, tokens, and event data are redacted;\n• uncertain mutations are reconciled instead of repeated.\n\nThese checks validate application handling. They do not prove provider\ndelivery, inbound signature compatibility, or live qualification.\n\nRelated documentation\n• Chatwoot capability index (README.md)\n• Chatwoot connector overview (../README.md)\n• Chatwoot connector configuration (../reference/configuration.md)\n• Authentication and account isolation (../getting-started/authentication-and-account-isolation.md)\n• Approvals and policy (../../../concepts/approvals-and-policy.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "4de5aee7cc83c315f69b7e24a34b7029e21402db5e8ab47165ecf5f945494539"
  }
}