{
  "schemaVersion": "1.0",
  "title": "Chatwoot connector configuration",
  "description": "This reference describes the configuration accepted by aip-host-chatwoot at the reviewed source revision. A complete process combines six Chatwoot-specific settings with the shared connector-host identity, storage, routing, lifecycle, and o",
  "canonical": "https://getaip.org/docs/connectors/chatwoot/reference/configuration",
  "route": "/docs/connectors/chatwoot/reference/configuration",
  "source": "docs/connectors/chatwoot/reference/configuration.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/chatwoot/reference/configuration.md",
    "txt": "/docs/download/connectors/chatwoot/reference/configuration.txt",
    "json": "/docs/download/connectors/chatwoot/reference/configuration.json",
    "pdf": "/docs/download/connectors/chatwoot/reference/configuration.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Chatwoot connector configuration\ndescription: >-\n  Look up Chatwoot host settings, defaults, limits, webhook dependencies, and\n  reload boundaries\nkind: reference\naudience: operator\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: chatwoot\naliases:\n  - Chatwoot environment variables\n  - Chatwoot host settings\n  - Chatwoot limits\n---\n\n# Chatwoot connector configuration\n\nThis reference describes the configuration accepted by\n`aip-host-chatwoot` at the reviewed source revision. A complete process combines\nsix Chatwoot-specific settings with the shared connector-host identity,\nstorage, routing, lifecycle, and optional event-delivery settings.\n\nAll product settings are read at startup. Only the shared non-secret\ncredential-revision policy is re-read before provider side effects.\n\n## Configuration identity\n\n| Property | Value |\n|---|---|\n| Binary | `aip-host-chatwoot` |\n| AIP workspace version | `1.0.0` |\n| Reviewed AIP source | `97be86e9efedf07ecf1783b03800f683f107fb04` |\n| Connector ID | `chatwoot` |\n| Connector profile | `aip.connector.chatwoot.v1` |\n| Pinned Chatwoot source | `8818d276b954ac4f84cffd8915c99f40e43804ed` |\n| Full capability surface | 150 catalogue operations plus three composites |\n\nEnvironment variables and flags contain non-secret values or filesystem paths.\nAPI tokens, webhook secrets, database credentials, and signing material belong\nin bounded owner-controlled files.\n\n## Chatwoot-specific settings\n\n| Environment variable | Command-line flag | Required | Default | Meaning |\n|---|---|---:|---|---|\n| `AIP_CHATWOOT_BASE_URL` | `--base-url` | Yes | None | Fixed Chatwoot origin |\n| `AIP_CHATWOOT_ACCOUNT_ID` | `--account-id` | Yes | None | Account inserted into every account-scoped route |\n| `AIP_CHATWOOT_API_TOKEN_FILE` | `--api-token-file` | Yes | None | Owner-only API-token file |\n| `AIP_CHATWOOT_WEBHOOK_SECRET_FILE` | `--webhook-secret-file` | No | Outbound-only host | Owner-only HMAC-secret file |\n| `AIP_CHATWOOT_MAX_RESPONSE_BYTES` | `--max-response-bytes` | No | `16777216` | Maximum buffered provider response |\n| `AIP_CHATWOOT_OPERATIONS_FILE` | `--operations-file` | No | All 150 catalogue operations | JSON suffix allowlist |\n\nThe API-token and webhook-secret readers accept at most 16 KiB. Both files\nmust pass the common secret-file type, ownership, permission, size, UTF-8, and\nnon-empty checks.\n\n### Provider origin and account\n\nThe provider base URL must be an origin:\n\n- HTTPS is required except for explicit loopback HTTP;\n- credentials, a path prefix, query, and fragment are rejected;\n- authenticated redirects are disabled;\n- the connection timeout is 10 seconds;\n- the overall provider request timeout is 120 seconds.\n\nThe account ID must contain 1 to 256 bytes, must not be blank after trimming,\nand must not contain control characters. It is inserted for\n`{account_id}` in every catalogue path and is not exposed as Action input.\n\n### Response-size setting\n\n`AIP_CHATWOOT_MAX_RESPONSE_BYTES` accepts an integer from `1` through\n`134217728` bytes. Omission uses `16777216` bytes.\n\nThe connector checks a declared `Content-Length` and also stops while streaming\nwhen accumulated bytes exceed the active limit. An oversized response becomes\n`connector.chatwoot.response_too_large` and is non-retryable. For an invocation,\nthe connector marks the external outcome uncertain because the provider may\nhave completed before the response was rejected.\n\n## Operation allowlist file\n\nThe optional operations file is a JSON array of exact catalogue suffixes. It\nis a non-secret configuration file with a 128 KiB size bound.\n\n```json\n[\n  \"account.get\",\n  \"agent.list\",\n  \"conversation.list\",\n  \"message.list\"\n]\n```\n\nRules:\n\n- every value must match one of the 150 compiled suffixes;\n- an unknown suffix fails startup;\n- an empty array fails startup;\n- duplicate suffixes collapse to one operation;\n- omission enables all 150 catalogue operations;\n- the three connector-level composites remain available and are not filtered\n  by this file.\n\nThe allowlist changes the discovered immutable manifest. Advance the connector\nversion and admission material when its effective set changes.\n\n## Relevant shared host settings\n\nThe global connector-host reference owns the complete shared matrix. The\nfollowing groups are required to understand Chatwoot behavior.\n\n### Identity and route binding\n\n| Setting | Role |\n|---|---|\n| `AIP_CONNECTOR_HOST_PUBLIC_ENDPOINT` | Externally reachable native endpoint ending in `/aip/v1/messages` |\n| `AIP_CONNECTOR_HOST_TYPE_ID` | Admitted Chatwoot connector type |\n| `AIP_CONNECTOR_HOST_VERSION_ID` | Immutable admitted version |\n| `AIP_CONNECTOR_HOST_INSTANCE_ID` | Logical one-account instance |\n| `AIP_CONNECTOR_HOST_REPLICA_ID` | Concrete process identity |\n| `AIP_CONNECTOR_HOST_TENANT_ID` | Verified tenant owned by the instance |\n| `AIP_CONNECTOR_HOST_MEMBERSHIP_ID` | Stable membership assertion |\n| `AIP_CONNECTOR_HOST_EXTERNAL_ACCOUNT_ID` | Deployment record for the Chatwoot account |\n| `AIP_CONNECTOR_HOST_EXTERNAL_ACCOUNT_SYSTEM` | Set to `chatwoot` with the external-account ID |\n| `AIP_CONNECTOR_HOST_ARTIFACT_DIGEST` | Exact running OCI digest |\n| `AIP_CONNECTOR_HOST_SECRET_PROVIDER_REF` | Non-secret provider reference |\n\nThe external-account ID and system are an optional pair. A Chatwoot deployment\nshould set them and validate the ID against `AIP_CHATWOOT_ACCOUNT_ID` outside\nthe binary; the reviewed code does not compare those two settings.\n\n### Storage, signing, gateway, and lifecycle\n\n| Setting | Required or default |\n|---|---|\n| `AIP_CONNECTOR_HOST_BIND` | Default `0.0.0.0:8081` |\n| `AIP_CONNECTOR_HOST_DATABASE_URL_FILE` | Required owner-only PostgreSQL URL |\n| `AIP_CONNECTOR_HOST_SIGNING_SEED_FILE` | Required owner-only Ed25519 seed |\n| `AIP_CONNECTOR_HOST_CONTROL_ENDPOINT` | Required fixed lifecycle endpoint |\n| `AIP_CONNECTOR_HOST_CONTROL_DID` or `_FILE` | Exactly one control-plane DID source |\n| `AIP_CONNECTOR_HOST_GATEWAY_PRINCIPAL_ID` | Required trusted gateway principal |\n| `AIP_CONNECTOR_HOST_GATEWAY_DID` or `_FILE` | Exactly one gateway DID source |\n| `AIP_CONNECTOR_HOST_TRUST_DOMAIN` | Required shared trust domain |\n| `AIP_CONNECTOR_HOST_TLS_CA_FILE` | Optional private-PKI root |\n| `AIP_CONNECTOR_HOST_MAX_IN_FLIGHT` | Default `32` |\n| `AIP_CONNECTOR_HOST_LEASE_TTL_MS` | Default `30000` |\n| `AIP_CONNECTOR_HOST_HEARTBEAT_MS` | Default `10000` |\n| `AIP_CONNECTOR_HOST_DRAIN_TIMEOUT_MS` | Default `30000` |\n| `AIP_CONNECTOR_HOST_HEALTH_TIMEOUT_MS` | Default `2000` |\n| `AIP_CONNECTOR_HOST_CONTROL_TIMEOUT_MS` | Default `5000` |\n\nShared credential ID, issuer, scopes, revision, and revision-policy settings\nare optional as a complete unit. They fence route authorization; they do not\nreplace the required Chatwoot token file.\n\n## Choose outbound-only or webhook-enabled mode\n\n### Outbound-only\n\nOmit `AIP_CHATWOOT_WEBHOOK_SECRET_FILE`. The process creates no\n`/webhooks/chatwoot` route, and shared central event delivery is not required\nfor startup.\n\nThe API token remains required because discovery health and outbound\ncapabilities use the account API.\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 webhook secret enables `POST /webhooks/chatwoot`. The central event\nendpoint becomes mandatory; startup fails if the publisher is absent.\n\nRelated event settings are:\n\n| Environment variable | Default | Meaning |\n|---|---:|---|\n| `AIP_CONNECTOR_HOST_EVENT_ENDPOINT` | None | Fixed central event ingress |\n| `AIP_CONNECTOR_HOST_EVENT_ALLOW_HTTP` | `false` | Permit HTTP only for an explicitly controlled deployment |\n| `AIP_CONNECTOR_HOST_EVENT_ALLOW_PRIVATE` | `false` | Permit a private destination explicitly |\n| `AIP_CONNECTOR_HOST_TLS_CA_FILE` | None | Optional CA for event-delivery TLS |\n\nNetwork exceptions without an event endpoint fail configuration. The event\ndestination is host-allowlisted, authenticated by the host signer, and pinned\nto the admitted event channel.\n\n## Request and payload limits\n\n| Boundary | Reviewed value |\n|---|---:|\n| Native AIP request body, common default | 4 MiB |\n| Provider JSON body encoder | 16 MiB |\n| Query properties | 128 |\n| Items in one query array | 256 |\n| JSON body properties | 512 |\n| Multipart fields | 512 |\n| Multipart files | 20 |\n| One decoded multipart file | 25 MiB |\n| All decoded multipart fields and files | 64 MiB |\n| One multipart field | 1 MiB |\n| One rendered path parameter | 512 bytes |\n| Provider response, default | 16 MiB |\n| Provider response, configurable maximum | 128 MiB |\n| Operations file | 128 KiB |\n| API token or webhook secret | 16 KiB |\n| Webhook request body | 1 MiB |\n| Webhook freshness window | 300 seconds |\n| Webhook replay identities | 10000 per instance-scoped state set |\n\nThe effective Action request ceiling is the smallest applicable boundary. A\n16 MiB provider JSON encoder does not increase the common 4 MiB native\nenvelope limit.\n\n## Webhook acceptance and event delivery\n\nThe webhook route requires:\n\n- `X-Chatwoot-Delivery` with a non-empty delivery identity;\n- `X-Chatwoot-Timestamp` parsed as an integer;\n- `X-Chatwoot-Signature` in `sha256=<hex>` form;\n- an original UTF-8 body of at most 1 MiB;\n- HMAC verification over timestamp, a dot, and the exact body;\n- a timestamp within five minutes of the host clock.\n\nAfter authentication, instance-scoped durable profile state fences the\ndelivery identity. The host maps a non-looping message to a deterministic AIP\nevent, appends it to the durable event log, and enqueues it on\n`chatwoot-webhooks`.\n\nA successful JSON response has this shape:\n\n```json\n{\n  \"accepted_events\": 1,\n  \"central_delivery\": \"centrally_acknowledged\"\n}\n```\n\n`central_delivery` is:\n\n| Value | Meaning |\n|---|---|\n| `centrally_acknowledged` | Central AIP acknowledged the durable batch before the response |\n| `durably_queued` | The batch is durable locally and the background publisher owns delivery |\n| `null` | No event was produced, such as for a connector-marked loop |\n\nAn HTTP `200` with `durably_queued` does not prove downstream consumption.\nStorage failure returns `503` before successful acceptance.\n\n## Readiness behavior\n\nThe Chatwoot product health probe performs an authenticated\n`GET /api/v1/accounts/<configured-account>`. A successful response supports\nreachability and credential validity for that account route.\n\nHost readiness also depends on durable storage, admitted identity, lifecycle\nlease, and common host state. It does not exercise all enabled operations,\nwebhook delivery, approval, mutation safety, or provider compatibility beyond\nthe health read.\n\n## Startup and reload boundaries\n\n| Value | Read |\n|---|---|\n| Provider origin and account | Startup |\n| API token | Startup |\n| Webhook secret and route mode | Startup |\n| Response limit | Startup |\n| Operation allowlist | Startup |\n| Common identity, topology, endpoints, and lifecycle limits | Startup |\n| Credential-revision policy file | Startup, then before provider side effects |\n\nChange any startup-owned value through a replacement replica and an admission\nor configuration revision. Do not edit a running process in place and assume\nits manifest, token, route, or webhook mode changed.\n\n## Configuration failures\n\n| Failure | Cause or decision |\n|---|---|\n| `invalid Chatwoot base URL` | Correct the origin; do not relax credentials, path, scheme, or redirect checks |\n| `invalid Chatwoot connector configuration` | Check account length, response bound, operation suffixes, and non-empty allowlist |\n| `configured Chatwoot credential is not valid UTF-8` | Repair the owner-only token file without printing it |\n| Unknown operation suffix | Use an exact compiled suffix or advance the source and admission package |\n| Webhook ingress requires event endpoint | Configure a valid central endpoint or remove the webhook-secret setting |\n| Event destination policy rejects the endpoint | Correct TLS, host, and explicit network policy |\n| `webhook.invalid_timestamp` | Supply an integer timestamp generated within the freshness window |\n| `webhook.authentication_failed` | Verify exact raw body, timestamp, signature encoding, and secret ownership |\n| `webhook.storage_unavailable` | Preserve the provider delivery ID and repair durable state before replay |\n| `connector.chatwoot.response_too_large` | Reconcile provider state before changing limits or retrying a mutation |\n\n## Related documentation\n\n- [Chatwoot connector overview](../README.md)\n- [Authenticate and isolate a Chatwoot account](../getting-started/authentication-and-account-isolation.md)\n- [Connector host configuration](../../../reference/connector-host-configuration.md)\n- [Connector host lifecycle](../../../guides/connector-host-lifecycle.md)\n- [Environment variables](../../../reference/environment-variables.md)\n",
    "text": "Chatwoot connector configuration\n\nThis reference describes the configuration accepted by\naip-host-chatwoot at the reviewed source revision. A complete process combines\nsix Chatwoot-specific settings with the shared connector-host identity,\nstorage, routing, lifecycle, and optional event-delivery settings.\n\nAll product settings are read at startup. Only the shared non-secret\ncredential-revision policy is re-read before provider side effects.\n\nConfiguration identity\n\n| Property | Value |\n\n| Binary | aip-host-chatwoot |\n| AIP workspace version | 1.0.0 |\n| Reviewed AIP source | 97be86e9efedf07ecf1783b03800f683f107fb04 |\n| Connector ID | chatwoot |\n| Connector profile | aip.connector.chatwoot.v1 |\n| Pinned Chatwoot source | 8818d276b954ac4f84cffd8915c99f40e43804ed |\n| Full capability surface | 150 catalogue operations plus three composites |\n\nEnvironment variables and flags contain non-secret values or filesystem paths.\nAPI tokens, webhook secrets, database credentials, and signing material belong\nin bounded owner-controlled files.\n\nChatwoot-specific settings\n\n| Environment variable | Command-line flag | Required | Default | Meaning |\n\n| AIPCHATWOOTBASEURL | --base-url | Yes | None | Fixed Chatwoot origin |\n| AIPCHATWOOTACCOUNTID | --account-id | Yes | None | Account inserted into every account-scoped route |\n| AIPCHATWOOTAPITOKENFILE | --api-token-file | Yes | None | Owner-only API-token file |\n| AIPCHATWOOTWEBHOOKSECRETFILE | --webhook-secret-file | No | Outbound-only host | Owner-only HMAC-secret file |\n| AIPCHATWOOTMAXRESPONSEBYTES | --max-response-bytes | No | 16777216 | Maximum buffered provider response |\n| AIPCHATWOOTOPERATIONSFILE | --operations-file | No | All 150 catalogue operations | JSON suffix allowlist |\n\nThe API-token and webhook-secret readers accept at most 16 KiB. Both files\nmust pass the common secret-file type, ownership, permission, size, UTF-8, and\nnon-empty checks.\n\nProvider origin and account\n\nThe provider base URL must be an origin:\n• HTTPS is required except for explicit loopback HTTP;\n• credentials, a path prefix, query, and fragment are rejected;\n• authenticated redirects are disabled;\n• the connection timeout is 10 seconds;\n• the overall provider request timeout is 120 seconds.\n\nThe account ID must contain 1 to 256 bytes, must not be blank after trimming,\nand must not contain control characters. It is inserted for\n{accountid} in every catalogue path and is not exposed as Action input.\n\nResponse-size setting\n\nAIPCHATWOOTMAXRESPONSEBYTES accepts an integer from 1 through\n134217728 bytes. Omission uses 16777216 bytes.\n\nThe connector checks a declared Content-Length and also stops while streaming\nwhen accumulated bytes exceed the active limit. An oversized response becomes\nconnector.chatwoot.responsetoolarge and is non-retryable. For an invocation,\nthe connector marks the external outcome uncertain because the provider may\nhave completed before the response was rejected.\n\nOperation allowlist file\n\nThe optional operations file is a JSON array of exact catalogue suffixes. It\nis a non-secret configuration file with a 128 KiB size bound.\n\n[\n  \"account.get\",\n  \"agent.list\",\n  \"conversation.list\",\n  \"message.list\"\n]\n\nRules:\n• every value must match one of the 150 compiled suffixes;\n• an unknown suffix fails startup;\n• an empty array fails startup;\n• duplicate suffixes collapse to one operation;\n• omission enables all 150 catalogue operations;\n• the three connector-level composites remain available and are not filtered\n  by this file.\n\nThe allowlist changes the discovered immutable manifest. Advance the connector\nversion and admission material when its effective set changes.\n\nRelevant shared host settings\n\nThe global connector-host reference owns the complete shared matrix. The\nfollowing groups are required to understand Chatwoot behavior.\n\nIdentity and route binding\n\n| Setting | Role |\n\n| AIPCONNECTORHOSTPUBLICENDPOINT | Externally reachable native endpoint ending in /aip/v1/messages |\n| AIPCONNECTORHOSTTYPEID | Admitted Chatwoot connector type |\n| AIPCONNECTORHOSTVERSIONID | Immutable admitted version |\n| AIPCONNECTORHOSTINSTANCEID | Logical one-account instance |\n| AIPCONNECTORHOSTREPLICAID | Concrete process identity |\n| AIPCONNECTORHOSTTENANTID | Verified tenant owned by the instance |\n| AIPCONNECTORHOSTMEMBERSHIPID | Stable membership assertion |\n| AIPCONNECTORHOSTEXTERNALACCOUNTID | Deployment record for the Chatwoot account |\n| AIPCONNECTORHOSTEXTERNALACCOUNTSYSTEM | Set to chatwoot with the external-account ID |\n| AIPCONNECTORHOSTARTIFACTDIGEST | Exact running OCI digest |\n| AIPCONNECTORHOSTSECRETPROVIDERREF | Non-secret provider reference |\n\nThe external-account ID and system are an optional pair. A Chatwoot deployment\nshould set them and validate the ID against AIPCHATWOOTACCOUNTID outside\nthe binary; the reviewed code does not compare those two settings.\n\nStorage, signing, gateway, and lifecycle\n\n| Setting | Required or default |\n\n| AIPCONNECTORHOSTBIND | Default 0.0.0.0:8081 |\n| AIPCONNECTORHOSTDATABASEURLFILE | Required owner-only PostgreSQL URL |\n| AIPCONNECTORHOSTSIGNINGSEEDFILE | Required owner-only Ed25519 seed |\n| AIPCONNECTORHOSTCONTROLENDPOINT | Required fixed lifecycle endpoint |\n| AIPCONNECTORHOSTCONTROLDID or FILE | Exactly one control-plane DID source |\n| AIPCONNECTORHOSTGATEWAYPRINCIPALID | Required trusted gateway principal |\n| AIPCONNECTORHOSTGATEWAYDID or FILE | Exactly one gateway DID source |\n| AIPCONNECTORHOSTTRUSTDOMAIN | Required shared trust domain |\n| AIPCONNECTORHOSTTLSCAFILE | Optional private-PKI root |\n| AIPCONNECTORHOSTMAXINFLIGHT | Default 32 |\n| AIPCONNECTORHOSTLEASETTLMS | Default 30000 |\n| AIPCONNECTORHOSTHEARTBEATMS | Default 10000 |\n| AIPCONNECTORHOSTDRAINTIMEOUTMS | Default 30000 |\n| AIPCONNECTORHOSTHEALTHTIMEOUTMS | Default 2000 |\n| AIPCONNECTORHOSTCONTROLTIMEOUTMS | Default 5000 |\n\nShared credential ID, issuer, scopes, revision, and revision-policy settings\nare optional as a complete unit. They fence route authorization; they do not\nreplace the required Chatwoot token file.\n\nChoose outbound-only or webhook-enabled mode\n\nOutbound-only\n\nOmit AIPCHATWOOTWEBHOOKSECRETFILE. The process creates no\n/webhooks/chatwoot route, and shared central event delivery is not required\nfor startup.\n\nThe API token remains required because discovery health and outbound\ncapabilities use the account API.\n\nWebhook-enabled\n\nSet:\n\nAIPCHATWOOTWEBHOOKSECRETFILE=/run/secrets/chatwoot-webhook-hmac\nAIPCONNECTORHOSTEVENTENDPOINT=https://aipd.example.test/aip/v1/connector-events\n\nThe webhook secret enables POST /webhooks/chatwoot. The central event\nendpoint becomes mandatory; startup fails if the publisher is absent.\n\nRelated event settings are:\n\n| Environment variable | Default | Meaning |\n\n| AIPCONNECTORHOSTEVENTENDPOINT | None | Fixed central event ingress |\n| AIPCONNECTORHOSTEVENTALLOWHTTP | false | Permit HTTP only for an explicitly controlled deployment |\n| AIPCONNECTORHOSTEVENTALLOWPRIVATE | false | Permit a private destination explicitly |\n| AIPCONNECTORHOSTTLSCAFILE | None | Optional CA for event-delivery TLS |\n\nNetwork exceptions without an event endpoint fail configuration. The event\ndestination is host-allowlisted, authenticated by the host signer, and pinned\nto the admitted event channel.\n\nRequest and payload limits\n\n| Boundary | Reviewed value |\n\n| Native AIP request body, common default | 4 MiB |\n| Provider JSON body encoder | 16 MiB |\n| Query properties | 128 |\n| Items in one query array | 256 |\n| JSON body properties | 512 |\n| Multipart fields | 512 |\n| Multipart files | 20 |\n| One decoded multipart file | 25 MiB |\n| All decoded multipart fields and files | 64 MiB |\n| One multipart field | 1 MiB |\n| One rendered path parameter | 512 bytes |\n| Provider response, default | 16 MiB |\n| Provider response, configurable maximum | 128 MiB |\n| Operations file | 128 KiB |\n| API token or webhook secret | 16 KiB |\n| Webhook request body | 1 MiB |\n| Webhook freshness window | 300 seconds |\n| Webhook replay identities | 10000 per instance-scoped state set |\n\nThe effective Action request ceiling is the smallest applicable boundary. A\n16 MiB provider JSON encoder does not increase the common 4 MiB native\nenvelope limit.\n\nWebhook acceptance and event delivery\n\nThe webhook route requires:\n• X-Chatwoot-Delivery with a non-empty delivery identity;\n• X-Chatwoot-Timestamp parsed as an integer;\n• X-Chatwoot-Signature in sha256= form;\n• an original UTF-8 body of at most 1 MiB;\n• HMAC verification over timestamp, a dot, and the exact body;\n• a timestamp within five minutes of the host clock.\n\nAfter authentication, instance-scoped durable profile state fences the\ndelivery identity. The host maps a non-looping message to a deterministic AIP\nevent, appends it to the durable event log, and enqueues it on\nchatwoot-webhooks.\n\nA successful JSON response has this shape:\n\n{\n  \"acceptedevents\": 1,\n  \"centraldelivery\": \"centrallyacknowledged\"\n}\n\ncentraldelivery is:\n\n| Value | Meaning |\n\n| centrallyacknowledged | Central AIP acknowledged the durable batch before the response |\n| durablyqueued | The batch is durable locally and the background publisher owns delivery |\n| null | No event was produced, such as for a connector-marked loop |\n\nAn HTTP 200 with durablyqueued does not prove downstream consumption.\nStorage failure returns 503 before successful acceptance.\n\nReadiness behavior\n\nThe Chatwoot product health probe performs an authenticated\nGET /api/v1/accounts/. A successful response supports\nreachability and credential validity for that account route.\n\nHost readiness also depends on durable storage, admitted identity, lifecycle\nlease, and common host state. It does not exercise all enabled operations,\nwebhook delivery, approval, mutation safety, or provider compatibility beyond\nthe health read.\n\nStartup and reload boundaries\n\n| Value | Read |\n\n| Provider origin and account | Startup |\n| API token | Startup |\n| Webhook secret and route mode | Startup |\n| Response limit | Startup |\n| Operation allowlist | Startup |\n| Common identity, topology, endpoints, and lifecycle limits | Startup |\n| Credential-revision policy file | Startup, then before provider side effects |\n\nChange any startup-owned value through a replacement replica and an admission\nor configuration revision. Do not edit a running process in place and assume\nits manifest, token, route, or webhook mode changed.\n\nConfiguration failures\n\n| Failure | Cause or decision |\n\n| invalid Chatwoot base URL | Correct the origin; do not relax credentials, path, scheme, or redirect checks |\n| invalid Chatwoot connector configuration | Check account length, response bound, operation suffixes, and non-empty allowlist |\n| configured Chatwoot credential is not valid UTF-8 | Repair the owner-only token file without printing it |\n| Unknown operation suffix | Use an exact compiled suffix or advance the source and admission package |\n| Webhook ingress requires event endpoint | Configure a valid central endpoint or remove the webhook-secret setting |\n| Event destination policy rejects the endpoint | Correct TLS, host, and explicit network policy |\n| webhook.invalidtimestamp | Supply an integer timestamp generated within the freshness window |\n| webhook.authenticationfailed | Verify exact raw body, timestamp, signature encoding, and secret ownership |\n| webhook.storageunavailable | Preserve the provider delivery ID and repair durable state before replay |\n| connector.chatwoot.responsetoolarge | Reconcile provider state before changing limits or retrying a mutation |\n\nRelated documentation\n• Chatwoot connector overview (../README.md)\n• Authenticate and isolate a Chatwoot account (../getting-started/authentication-and-account-isolation.md)\n• Connector host configuration (../../../reference/connector-host-configuration.md)\n• Connector host lifecycle (../../../guides/connector-host-lifecycle.md)\n• Environment variables (../../../reference/environment-variables.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "2718ab5d92bb5087456dbf76bd8bd0fb863ecad2293e8fe3ea2a516c42d02891"
  }
}