{
  "schemaVersion": "1.0",
  "title": "Deploy the Chatwoot connector",
  "description": "Use this guide to deploy one immutable aip-host-chatwoot instance for one Chatwoot account. The result is an admitted, durable, observable route that can be replaced or rolled back without changing central aipd.",
  "canonical": "https://getaip.org/docs/connectors/chatwoot/operations/deployment",
  "route": "/docs/connectors/chatwoot/operations/deployment",
  "source": "docs/connectors/chatwoot/operations/deployment.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/chatwoot/operations/deployment.md",
    "txt": "/docs/download/connectors/chatwoot/operations/deployment.txt",
    "json": "/docs/download/connectors/chatwoot/operations/deployment.json",
    "pdf": "/docs/download/connectors/chatwoot/operations/deployment.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Deploy the Chatwoot connector\ndescription: >-\n  Deploy one immutable, account-bound Chatwoot host with admitted identity,\n  durable state, safe readiness gates, and controlled rollback\nkind: how-to\naudience: operator\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: chatwoot\naliases:\n  - Chatwoot connector deployment\n  - Run aip-host-chatwoot\n---\n\n# Deploy the Chatwoot connector\n\nUse this guide to deploy one immutable `aip-host-chatwoot` instance for one\nChatwoot account. The result is an admitted, durable, observable route that can\nbe replaced or rolled back without changing central `aipd`.\n\nThis is a production design procedure. The repository Compose stack is useful\nqualification evidence, but it is not a production deployment template.\n\n## Deployment boundary\n\nOne logical connector instance owns:\n\n- one admitted connector type and immutable version;\n- one tenant;\n- one Chatwoot account;\n- one provider origin and API token;\n- one durable host-state boundary;\n- one or more separately identified replicas, each with a fixed native AIP\n  endpoint;\n- an optional Chatwoot webhook ingress and central Event route.\n\nThe process serves native AIP on a configurable bind address, defaulting to\n`0.0.0.0:8081`. Its advertised endpoint must be an absolute HTTPS URL ending\nexactly in `/aip/v1/messages`. Explicit loopback development can opt into HTTP;\nproduction cannot.\n\n## Topology and ownership\n\n| Connection | Direction | Owner | Required protection |\n|---|---|---|---|\n| Gateway to host | Inbound native AIP | AIP platform | TLS, signed envelopes, trusted gateway identity |\n| Lifecycle service to host | Inbound control | AIP platform | Fixed endpoint, DID verification, sequence and replay fencing |\n| Host to Chatwoot | Outbound provider API | Connector operator | HTTPS origin, owner-only API token, no authenticated redirects |\n| Host to PostgreSQL | Durable runtime state | Connector operator | Dedicated least-privilege URL file and migrations |\n| Chatwoot to host | Optional webhook | Provider and connector operator | TLS, raw-body HMAC, freshness, replay state |\n| Host to central Event ingress | Optional signed publication | AIP platform | Fixed endpoint, host signer, durable outbox |\n\nKeep the host port private behind the selected TLS edge. Expose only the native\nendpoint and, when enabled, `POST /webhooks/chatwoot`.\n\nEvery replica of one logical instance uses a unique replica ID. Replicas share\nthe admitted version, instance identity, external account, and durable state\nneeded for leases, replay fencing, and Event publication.\n\n## 1. Freeze the release unit\n\nBefore provisioning, record:\n\n| Release evidence | Required value |\n|---|---|\n| AIP source revision | Exact commit |\n| Chatwoot connector image | Immutable OCI digest |\n| Workspace version | Version embedded in the artifact |\n| Connector type and version | Exact admitted IDs |\n| Upstream Chatwoot baseline | `8818d276b954ac4f84cffd8915c99f40e43804ed` |\n| Capability surface | Three composites plus the effective operation allowlist |\n| Configuration revision | Positive monotonic value |\n| Admission package | Signed package bound to artifact and manifest |\n| Trust policy | Exact policy used to admit the version |\n\nDo not deploy from a mutable image tag alone. If an operations allowlist\nchanges, the immutable manifest changes. Advance the connector version and its\nadmission material before routing work to it.\n\nThe source fleet preparation script derives a source digest, image tag, image\nID, release ID, and release revision. That is a useful reference pattern, not\nevidence for an image that was built elsewhere.\n\n## 2. Bind the external account\n\nSet one stable Chatwoot account in:\n\n```text\nAIP_CHATWOOT_ACCOUNT_ID\n```\n\nBind the same account boundary in the connector registry through:\n\n```text\nAIP_CONNECTOR_HOST_EXTERNAL_ACCOUNT_ID\nAIP_CONNECTOR_HOST_EXTERNAL_ACCOUNT_SYSTEM=chatwoot\n```\n\nThe reviewed binary inserts `AIP_CHATWOOT_ACCOUNT_ID` into provider routes but\ndoes not compare it with the registry external-account ID. Enforce equality in\ndeployment policy and admission review.\n\nUse a separate logical instance for another Chatwoot account. Do not let an\nAction select `account_id`.\n\n## 3. Provision durable state\n\nGive the host an owner-only PostgreSQL URL file through:\n\n```text\nAIP_CONNECTOR_HOST_DATABASE_URL_FILE\n```\n\nThe host runtime uses durable state for Action handling, lifecycle recovery,\nprofile state, webhook replay fencing, local Events, and the central Event\noutbox. Provision and migrate it before a replica registers.\n\nAll replicas of one logical instance need a coherent storage authority.\nProcess-local or independently provisioned state cannot provide shared replay,\nlease, or outbox behavior.\n\nBack up and restore this state as one documented recovery unit. Never clear\nreplay or outbox records merely to make readiness green.\n\n## 4. Place identity and trust material\n\nProvision the shared connector-host identity fields:\n\n- connector type, version, instance, and unique replica IDs;\n- tenant and membership IDs;\n- immutable artifact digest;\n- public native endpoint;\n- trust domain;\n- trusted gateway principal and DID;\n- fixed control-plane endpoint and DID;\n- host signing seed file;\n- optional private-PKI CA file;\n- credential ID, issuer, scopes, revision, and revision-policy file.\n\nSigning seeds, database URLs, API tokens, webhook secrets, and private CA\nmaterial belong in bounded owner-controlled files. Environment variables carry\npaths and non-secret identifiers.\n\nThe public endpoint identity, admitted version, manifest digest, and replica\nsigner must agree. Do not reuse a replica signing identity across unrelated\ninstances.\n\n## 5. Configure the provider boundary\n\nSet:\n\n```text\nAIP_CHATWOOT_BASE_URL=https://chatwoot.example.test\nAIP_CHATWOOT_ACCOUNT_ID=<stable-account-id>\nAIP_CHATWOOT_API_TOKEN_FILE=/run/secrets/chatwoot-api-token\n```\n\nThe provider URL must be an origin without credentials, path, query, or\nfragment. HTTPS is required outside explicit loopback development.\n\nThe token file must be owner-controlled, non-empty UTF-8, and at most 16 KiB.\nGive the token only the provider permissions required by the admitted\ncapability surface.\n\nOptional product controls are:\n\n| Setting | Deployment decision |\n|---|---|\n| `AIP_CHATWOOT_OPERATIONS_FILE` | Exact JSON suffix allowlist; omission admits all 150 catalogue operations |\n| `AIP_CHATWOOT_MAX_RESPONSE_BYTES` | Bounded response limit from 1 through 134,217,728 bytes |\n\nThe three connector composites are not filtered by the operations file. Apply\ntenant policy separately when one must be unavailable.\n\n## 6. Choose the ingress mode\n\n### Outbound-only\n\nOmit `AIP_CHATWOOT_WEBHOOK_SECRET_FILE`. The process creates no Chatwoot\nwebhook route and does not require a central Event endpoint.\n\nUse this mode when AIP only calls Chatwoot and no provider Event must enter\nthrough this host.\n\n### Webhook-enabled\n\nSet:\n\n```text\nAIP_CHATWOOT_WEBHOOK_SECRET_FILE=/run/secrets/chatwoot-webhook-hmac\nAIP_CONNECTOR_HOST_EVENT_ENDPOINT=https://aipd.example.test/aip/v1/connector-events\n```\n\nThe host refuses this mode when the signed Event publisher is unavailable.\nRoute Chatwoot traffic to `POST /webhooks/chatwoot` without altering the three\nheaders or body bytes.\n\nThe Event endpoint must pass fixed-host, TLS, private-network, and signer\npolicy. A webhook secret does not replace those central publication controls.\n\n## 7. Admit before starting\n\nApply the connector admission package and trust policy before the replica\nstarts. Admission must bind:\n\n- connector type and immutable version;\n- semantic manifest and capability set;\n- artifact digest and provenance;\n- supported native and connector profiles;\n- external-account and tenant policy;\n- public endpoint and lifecycle expectations.\n\nUse separate registry credentials for admission, lifecycle control, and\ndata-plane reads. The host must not receive an administrator credential.\n\nThe source qualification graph runs `admit-chatwoot` before\n`chatwoot-acme-a`. Preserve that dependency in the production orchestrator,\neven when service names differ.\n\n## 8. Start dependencies in order\n\nUse this order:\n\n1. durable PostgreSQL and required migrations;\n2. connector registry and the admitted Chatwoot version;\n3. control plane and trusted gateway;\n4. TLS edge and fixed internal routes;\n5. central callback and Event ingress when configured;\n6. the Chatwoot host replica;\n7. lifecycle registration and lease renewal;\n8. readiness and safe canary checks;\n9. production route enablement.\n\nStop when any earlier authority is unavailable. Do not start the host with a\ntemporary identity, unadmitted version, mutable digest, or substitute account.\n\nThe source qualification service also waits for its controlled provider\nfixture and two healthy gateways. Replace fixture dependencies with real\nprovider and platform readiness ownership; do not copy fixture hostnames into\nproduction.\n\n## 9. Gate readiness\n\nRequire all of these signals:\n\n| Gate | Established fact |\n|---|---|\n| Process health | Host server and local supervisor are running |\n| Durable store | Required runtime and profile-state operations are available |\n| Admission | Type, version, instance, replica, artifact, and manifest match |\n| Lifecycle lease | Replica is registered, healthy, and not draining |\n| Product health | Authenticated account GET succeeded for the configured account |\n| Route | Gateway resolves the admitted instance and replica |\n| Webhook mode, when enabled | Replay state and central Event publisher are configured |\n\nThe product health probe calls:\n\n```text\nGET /api/v1/accounts/{configured_account_id}\n```\n\nIt proves account-route reachability and token acceptance at that moment. It\ndoes not validate every capability, webhook delivery, approval path, or\nmutation payload.\n\n## 10. Run a safe canary\n\nBefore admitting mutations:\n\n1. read the discovered manifest through the tenant route;\n2. verify connector ID, version, profiles, and effective capabilities;\n3. call `cap:chatwoot:account.get` with a new read Action ID;\n4. confirm the result belongs to the configured account;\n5. retain gateway, route, host, and provider request identities;\n6. verify no unexpected replica or account served the Action.\n\nWhen webhook mode is enabled, add a provider-controlled signed delivery. Check\nthat a non-looping delivery becomes one local Event and either reaches central\nAIP or reports `durably_queued`. Verify a connector-marked loop produces zero\nEvents.\n\nDo not use a customer-visible message, deletion, import, export, merge, macro,\nor handoff as the first canary.\n\n## 11. Enable traffic gradually\n\nRoute a bounded tenant and capability subset first. Observe:\n\n- Action admission and completion;\n- provider authentication and request identities;\n- host lease and in-flight counts;\n- response-size failures;\n- uncertain provider outcomes;\n- webhook replay, Event persistence, and outbox backlog when enabled.\n\nExpand only after the safe read path, approval path, and recovery ownership are\nunderstood. Readiness alone is not a rollout success criterion.\n\n## Replace a replica\n\nFor a same-version replacement:\n\n1. provision a new replica ID and signer;\n2. start it against the same logical instance and coherent durable state;\n3. wait for registration, health, lease, route, and safe canary gates;\n4. stop new assignments to the old replica;\n5. allow pinned work to settle within the drain boundary;\n6. mark the old replica offline and stop it;\n7. retain lifecycle and Action evidence.\n\nConfiguration that changes the manifest, account, provider origin, capability\nset, or artifact belongs to a new immutable version or instance. Do not relabel\nan existing admitted version.\n\n## Roll back safely\n\nKeep the previous artifact, admission record, configuration, and provider\ncompatibility decision available until the new version clears its rollout\nwindow.\n\nRollback means routing new work to a previously admitted compatible version,\nnot overwriting the failed version in place. Preserve:\n\n- current durable Action and Event state;\n- idempotency records;\n- webhook replay and outbox state;\n- provider request correlation;\n- pinned work on the replica that owns it.\n\nDrain the regressed replica before removing it. Do not move an ambiguous\nprovider mutation to another replica under a new Action ID.\n\n## Deployment failures\n\n| Failure | Stop condition and response |\n|---|---|\n| Admission mismatch | Do not register; reconcile artifact, manifest, version, and trust policy |\n| Account identities differ | Do not route work; correct deployment policy and use one stable account |\n| API token rejected | Keep route unavailable; rotate the owner-only file and credential revision |\n| Provider origin invalid | Correct the HTTPS origin; do not weaken URL or redirect policy |\n| Durable state unavailable | Keep readiness false; restore storage before lifecycle or webhook acceptance |\n| Event endpoint missing in webhook mode | Fail startup or return to outbound-only mode intentionally |\n| Product health fails | Preserve bounded diagnostics; do not prove health with an unrelated endpoint |\n| Canary served by wrong route | Remove traffic and correct registry or gateway identity |\n| New version regresses | Stop expansion, drain it, and route new work to the compatible admitted version |\n\n## Deployment evidence\n\nRetain:\n\n- source revision, image digest, SBOM and provenance identity;\n- connector type, version, instance, replica, tenant, and external account;\n- manifest and operations-allowlist hashes;\n- admission package and trust-policy identity;\n- configuration revision and credential revision;\n- migration and startup outcomes;\n- health, lease, route, and canary observations;\n- webhook and outbox checks when enabled;\n- rollout, drain, rollback, and operator decisions.\n\nDo not retain secret contents or unredacted provider payloads as deployment\nevidence.\n\n## Completion criteria\n\nDeployment is complete only when:\n\n- the immutable artifact and manifest match admission;\n- provider and registry account boundaries agree;\n- secrets and signing material are owner-controlled files;\n- storage, identity, control, gateway, and TLS dependencies are healthy;\n- the replica holds a valid non-draining lease;\n- product health and the safe account-read canary pass;\n- webhook mode, when enabled, has durable replay and Event delivery ownership;\n- rollback artifacts and procedures remain available;\n- no mutation is used to substitute for a safe deployment check.\n\nThese gates establish a controlled deployment path. They do not establish\nproduction qualification for every Chatwoot capability.\n\n## Related documentation\n\n- [Chatwoot connector configuration](../reference/configuration.md)\n- [Run the Chatwoot connector quickstart](../getting-started/quickstart.md)\n- [Production deployment](../../../guides/production-deployment.md)\n- [Deploy the connector fleet](../../../guides/deploy-connector-fleet.md)\n- [Connector host lifecycle](../../../guides/connector-host-lifecycle.md)\n",
    "text": "Deploy the Chatwoot connector\n\nUse this guide to deploy one immutable aip-host-chatwoot instance for one\nChatwoot account. The result is an admitted, durable, observable route that can\nbe replaced or rolled back without changing central aipd.\n\nThis is a production design procedure. The repository Compose stack is useful\nqualification evidence, but it is not a production deployment template.\n\nDeployment boundary\n\nOne logical connector instance owns:\n• one admitted connector type and immutable version;\n• one tenant;\n• one Chatwoot account;\n• one provider origin and API token;\n• one durable host-state boundary;\n• one or more separately identified replicas, each with a fixed native AIP\n  endpoint;\n• an optional Chatwoot webhook ingress and central Event route.\n\nThe process serves native AIP on a configurable bind address, defaulting to\n0.0.0.0:8081. Its advertised endpoint must be an absolute HTTPS URL ending\nexactly in /aip/v1/messages. Explicit loopback development can opt into HTTP;\nproduction cannot.\n\nTopology and ownership\n\n| Connection | Direction | Owner | Required protection |\n\n| Gateway to host | Inbound native AIP | AIP platform | TLS, signed envelopes, trusted gateway identity |\n| Lifecycle service to host | Inbound control | AIP platform | Fixed endpoint, DID verification, sequence and replay fencing |\n| Host to Chatwoot | Outbound provider API | Connector operator | HTTPS origin, owner-only API token, no authenticated redirects |\n| Host to PostgreSQL | Durable runtime state | Connector operator | Dedicated least-privilege URL file and migrations |\n| Chatwoot to host | Optional webhook | Provider and connector operator | TLS, raw-body HMAC, freshness, replay state |\n| Host to central Event ingress | Optional signed publication | AIP platform | Fixed endpoint, host signer, durable outbox |\n\nKeep the host port private behind the selected TLS edge. Expose only the native\nendpoint and, when enabled, POST /webhooks/chatwoot.\n\nEvery replica of one logical instance uses a unique replica ID. Replicas share\nthe admitted version, instance identity, external account, and durable state\nneeded for leases, replay fencing, and Event publication.\n1. Freeze the release unit\n\nBefore provisioning, record:\n\n| Release evidence | Required value |\n\n| AIP source revision | Exact commit |\n| Chatwoot connector image | Immutable OCI digest |\n| Workspace version | Version embedded in the artifact |\n| Connector type and version | Exact admitted IDs |\n| Upstream Chatwoot baseline | 8818d276b954ac4f84cffd8915c99f40e43804ed |\n| Capability surface | Three composites plus the effective operation allowlist |\n| Configuration revision | Positive monotonic value |\n| Admission package | Signed package bound to artifact and manifest |\n| Trust policy | Exact policy used to admit the version |\n\nDo not deploy from a mutable image tag alone. If an operations allowlist\nchanges, the immutable manifest changes. Advance the connector version and its\nadmission material before routing work to it.\n\nThe source fleet preparation script derives a source digest, image tag, image\nID, release ID, and release revision. That is a useful reference pattern, not\nevidence for an image that was built elsewhere.\n2. Bind the external account\n\nSet one stable Chatwoot account in:\n\nAIPCHATWOOTACCOUNTID\n\nBind the same account boundary in the connector registry through:\n\nAIPCONNECTORHOSTEXTERNALACCOUNTID\nAIPCONNECTORHOSTEXTERNALACCOUNTSYSTEM=chatwoot\n\nThe reviewed binary inserts AIPCHATWOOTACCOUNTID into provider routes but\ndoes not compare it with the registry external-account ID. Enforce equality in\ndeployment policy and admission review.\n\nUse a separate logical instance for another Chatwoot account. Do not let an\nAction select accountid.\n3. Provision durable state\n\nGive the host an owner-only PostgreSQL URL file through:\n\nAIPCONNECTORHOSTDATABASEURLFILE\n\nThe host runtime uses durable state for Action handling, lifecycle recovery,\nprofile state, webhook replay fencing, local Events, and the central Event\noutbox. Provision and migrate it before a replica registers.\n\nAll replicas of one logical instance need a coherent storage authority.\nProcess-local or independently provisioned state cannot provide shared replay,\nlease, or outbox behavior.\n\nBack up and restore this state as one documented recovery unit. Never clear\nreplay or outbox records merely to make readiness green.\n4. Place identity and trust material\n\nProvision the shared connector-host identity fields:\n• connector type, version, instance, and unique replica IDs;\n• tenant and membership IDs;\n• immutable artifact digest;\n• public native endpoint;\n• trust domain;\n• trusted gateway principal and DID;\n• fixed control-plane endpoint and DID;\n• host signing seed file;\n• optional private-PKI CA file;\n• credential ID, issuer, scopes, revision, and revision-policy file.\n\nSigning seeds, database URLs, API tokens, webhook secrets, and private CA\nmaterial belong in bounded owner-controlled files. Environment variables carry\npaths and non-secret identifiers.\n\nThe public endpoint identity, admitted version, manifest digest, and replica\nsigner must agree. Do not reuse a replica signing identity across unrelated\ninstances.\n5. Configure the provider boundary\n\nSet:\n\nAIPCHATWOOTBASEURL=https://chatwoot.example.test\nAIPCHATWOOTACCOUNTID=\nAIPCHATWOOTAPITOKENFILE=/run/secrets/chatwoot-api-token\n\nThe provider URL must be an origin without credentials, path, query, or\nfragment. HTTPS is required outside explicit loopback development.\n\nThe token file must be owner-controlled, non-empty UTF-8, and at most 16 KiB.\nGive the token only the provider permissions required by the admitted\ncapability surface.\n\nOptional product controls are:\n\n| Setting | Deployment decision |\n\n| AIPCHATWOOTOPERATIONSFILE | Exact JSON suffix allowlist; omission admits all 150 catalogue operations |\n| AIPCHATWOOTMAXRESPONSEBYTES | Bounded response limit from 1 through 134,217,728 bytes |\n\nThe three connector composites are not filtered by the operations file. Apply\ntenant policy separately when one must be unavailable.\n6. Choose the ingress mode\n\nOutbound-only\n\nOmit AIPCHATWOOTWEBHOOKSECRETFILE. The process creates no Chatwoot\nwebhook route and does not require a central Event endpoint.\n\nUse this mode when AIP only calls Chatwoot and no provider Event must enter\nthrough this host.\n\nWebhook-enabled\n\nSet:\n\nAIPCHATWOOTWEBHOOKSECRETFILE=/run/secrets/chatwoot-webhook-hmac\nAIPCONNECTORHOSTEVENTENDPOINT=https://aipd.example.test/aip/v1/connector-events\n\nThe host refuses this mode when the signed Event publisher is unavailable.\nRoute Chatwoot traffic to POST /webhooks/chatwoot without altering the three\nheaders or body bytes.\n\nThe Event endpoint must pass fixed-host, TLS, private-network, and signer\npolicy. A webhook secret does not replace those central publication controls.\n7. Admit before starting\n\nApply the connector admission package and trust policy before the replica\nstarts. Admission must bind:\n• connector type and immutable version;\n• semantic manifest and capability set;\n• artifact digest and provenance;\n• supported native and connector profiles;\n• external-account and tenant policy;\n• public endpoint and lifecycle expectations.\n\nUse separate registry credentials for admission, lifecycle control, and\ndata-plane reads. The host must not receive an administrator credential.\n\nThe source qualification graph runs admit-chatwoot before\nchatwoot-acme-a. Preserve that dependency in the production orchestrator,\neven when service names differ.\n8. Start dependencies in order\n\nUse this order:\n1. durable PostgreSQL and required migrations;\n2. connector registry and the admitted Chatwoot version;\n3. control plane and trusted gateway;\n4. TLS edge and fixed internal routes;\n5. central callback and Event ingress when configured;\n6. the Chatwoot host replica;\n7. lifecycle registration and lease renewal;\n8. readiness and safe canary checks;\n9. production route enablement.\n\nStop when any earlier authority is unavailable. Do not start the host with a\ntemporary identity, unadmitted version, mutable digest, or substitute account.\n\nThe source qualification service also waits for its controlled provider\nfixture and two healthy gateways. Replace fixture dependencies with real\nprovider and platform readiness ownership; do not copy fixture hostnames into\nproduction.\n9. Gate readiness\n\nRequire all of these signals:\n\n| Gate | Established fact |\n\n| Process health | Host server and local supervisor are running |\n| Durable store | Required runtime and profile-state operations are available |\n| Admission | Type, version, instance, replica, artifact, and manifest match |\n| Lifecycle lease | Replica is registered, healthy, and not draining |\n| Product health | Authenticated account GET succeeded for the configured account |\n| Route | Gateway resolves the admitted instance and replica |\n| Webhook mode, when enabled | Replay state and central Event publisher are configured |\n\nThe product health probe calls:\n\nGET /api/v1/accounts/{configuredaccountid}\n\nIt proves account-route reachability and token acceptance at that moment. It\ndoes not validate every capability, webhook delivery, approval path, or\nmutation payload.\n10. Run a safe canary\n\nBefore admitting mutations:\n1. read the discovered manifest through the tenant route;\n2. verify connector ID, version, profiles, and effective capabilities;\n3. call cap:chatwoot:account.get with a new read Action ID;\n4. confirm the result belongs to the configured account;\n5. retain gateway, route, host, and provider request identities;\n6. verify no unexpected replica or account served the Action.\n\nWhen webhook mode is enabled, add a provider-controlled signed delivery. Check\nthat a non-looping delivery becomes one local Event and either reaches central\nAIP or reports durablyqueued. Verify a connector-marked loop produces zero\nEvents.\n\nDo not use a customer-visible message, deletion, import, export, merge, macro,\nor handoff as the first canary.\n11. Enable traffic gradually\n\nRoute a bounded tenant and capability subset first. Observe:\n• Action admission and completion;\n• provider authentication and request identities;\n• host lease and in-flight counts;\n• response-size failures;\n• uncertain provider outcomes;\n• webhook replay, Event persistence, and outbox backlog when enabled.\n\nExpand only after the safe read path, approval path, and recovery ownership are\nunderstood. Readiness alone is not a rollout success criterion.\n\nReplace a replica\n\nFor a same-version replacement:\n1. provision a new replica ID and signer;\n2. start it against the same logical instance and coherent durable state;\n3. wait for registration, health, lease, route, and safe canary gates;\n4. stop new assignments to the old replica;\n5. allow pinned work to settle within the drain boundary;\n6. mark the old replica offline and stop it;\n7. retain lifecycle and Action evidence.\n\nConfiguration that changes the manifest, account, provider origin, capability\nset, or artifact belongs to a new immutable version or instance. Do not relabel\nan existing admitted version.\n\nRoll back safely\n\nKeep the previous artifact, admission record, configuration, and provider\ncompatibility decision available until the new version clears its rollout\nwindow.\n\nRollback means routing new work to a previously admitted compatible version,\nnot overwriting the failed version in place. Preserve:\n• current durable Action and Event state;\n• idempotency records;\n• webhook replay and outbox state;\n• provider request correlation;\n• pinned work on the replica that owns it.\n\nDrain the regressed replica before removing it. Do not move an ambiguous\nprovider mutation to another replica under a new Action ID.\n\nDeployment failures\n\n| Failure | Stop condition and response |\n\n| Admission mismatch | Do not register; reconcile artifact, manifest, version, and trust policy |\n| Account identities differ | Do not route work; correct deployment policy and use one stable account |\n| API token rejected | Keep route unavailable; rotate the owner-only file and credential revision |\n| Provider origin invalid | Correct the HTTPS origin; do not weaken URL or redirect policy |\n| Durable state unavailable | Keep readiness false; restore storage before lifecycle or webhook acceptance |\n| Event endpoint missing in webhook mode | Fail startup or return to outbound-only mode intentionally |\n| Product health fails | Preserve bounded diagnostics; do not prove health with an unrelated endpoint |\n| Canary served by wrong route | Remove traffic and correct registry or gateway identity |\n| New version regresses | Stop expansion, drain it, and route new work to the compatible admitted version |\n\nDeployment evidence\n\nRetain:\n• source revision, image digest, SBOM and provenance identity;\n• connector type, version, instance, replica, tenant, and external account;\n• manifest and operations-allowlist hashes;\n• admission package and trust-policy identity;\n• configuration revision and credential revision;\n• migration and startup outcomes;\n• health, lease, route, and canary observations;\n• webhook and outbox checks when enabled;\n• rollout, drain, rollback, and operator decisions.\n\nDo not retain secret contents or unredacted provider payloads as deployment\nevidence.\n\nCompletion criteria\n\nDeployment is complete only when:\n• the immutable artifact and manifest match admission;\n• provider and registry account boundaries agree;\n• secrets and signing material are owner-controlled files;\n• storage, identity, control, gateway, and TLS dependencies are healthy;\n• the replica holds a valid non-draining lease;\n• product health and the safe account-read canary pass;\n• webhook mode, when enabled, has durable replay and Event delivery ownership;\n• rollback artifacts and procedures remain available;\n• no mutation is used to substitute for a safe deployment check.\n\nThese gates establish a controlled deployment path. They do not establish\nproduction qualification for every Chatwoot capability.\n\nRelated documentation\n• Chatwoot connector configuration (../reference/configuration.md)\n• Run the Chatwoot connector quickstart (../getting-started/quickstart.md)\n• Production deployment (../../../guides/production-deployment.md)\n• Deploy the connector fleet (../../../guides/deploy-connector-fleet.md)\n• Connector host lifecycle (../../../guides/connector-host-lifecycle.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "712dd8a3fd48c7657e266392420e06697394fe7457b0f6956f7c3b07ecc9db84"
  }
}