Troubleshoot the Chatwoot connector

Use this runbook to identify the boundary that failed and choose the narrowest safe next action. It covers process startup, connector-host readiness, signed Action handling, Chatwoot provider calls, webhook ingress, and durable Event delivery.

Pause new mutations whenever provider outcome is uncertain. Preserve the original Action ID, idempotency key, account ID, route assignment, remote status, webhook delivery ID, and durable state before changing a deployment.

Identify the error surface

Start with the surface that produced the evidence. The same HTTP status can represent different trust and recovery boundaries.

Automate on the exact code, category, retry flag, uncertain_outcome, and durable state. Message text is diagnostic and is not a stable interface.

Choose the first check

Resolve startup failures

Startup failures occur before a protocol error can be returned. Compare the first process error with the configured base URL, account ID, token file, response limit, allowed-operation set, webhook secret, PostgreSQL state, central Event endpoint, manifest, and immutable host identity.

Correct one owning boundary at a time. Require /ready and route a safe account read through aipd after a repair. A direct Chatwoot request does not prove the AIP tenant, route, approval, or signing boundary.

Follow readiness to its owner

/health is a process-liveness response. /ready succeeds only while the host is not draining, its lease is valid, durable storage is ready, and the authenticated Chatwoot account probe succeeds.

Use the operations runbook for containment, heartbeat recovery, replacement, and rollback. Readiness does not prove every Chatwoot operation or webhook delivery path.

Look up Chatwoot connector codes

The table covers every explicit connector.chatwoot.* code at the reviewed revision. All connector failures set automatic retryable to false.

connector.chatwoot.webhook_replay exists in the typed error mapping, but the ordinary duplicate webhook path does not construct it. That path reproduces a deterministic Event ID so durable Event storage can deduplicate the delivery.

Look up connector-host codes

The host can reject a request before Chatwoot is called. Product-neutral trust, route, credential-revision, approval, replay, and execution codes are defined in the global error reference. These compact or immediate host codes often identify the first diagnostic branch.

A signed host code such as connector_host.authentication, connector_host.route_mismatch, or connector_host.credential_revision_denied identifies a host policy boundary, not a Chatwoot credential result. Keep the original signed envelope when escalating.

Look up webhook HTTP codes

The standalone ingress route returns a compact error rather than an AIP error envelope.

An HTTP 200 can report a locally accepted Event whose central publication is still queued. Recover the durable outbox instead of asking Chatwoot to create a new webhook or repeating the Action that caused it.

Decide whether to retry

Apply these checks in order and stop at the first unmet condition:

1. verify the signed response or read the durable Action result;
2. classify the operation as a read, mutation, or webhook delivery;
3. for a mutation, establish provider outcome from authoritative state;
4. require published implementation retry support;
5. require retryable not to be false;
6. keep the same Action, input, and idempotency key;
7. respect attempt, elapsed-time, and backoff limits.

At this revision, the conversation-status composite and the 62 catalogue reads publish retry support. Connector-mapped failures still set retryable to false. The host capacity and not-ready codes can carry retryable: true, but that hint cannot override operation safety or the Action budget.

Treat uncertain outcomes as nonterminal

remote_temporary, transport, response_too_large, and cancelled can mark an invocation outcome uncertain. Stop new mutations for the affected resource, retain the original identifiers, read Chatwoot and AIP state, and decide whether the intended effect is present before any compensation or replacement Action.

The connector does not publish transaction or reconciliation support. Recovery therefore uses the canonical provider resource reads and the original durable Action evidence. A temporary category or missing provider request ID is never proof that a mutation did not happen.

Collect minimum evidence

Retain a bounded incident bundle before changing configuration or state:

• UTC interval, deployment revision, instance ID, replica ID, and account ID;
• Action ID, correlation ID, capability ID, route assignment, and key reference;
• exact code, category, retry flag, uncertainty flag, and remote status;
• readiness snapshot and the eight process-local host metrics;
• redacted provider resource state for an uncertain mutation;
• webhook delivery ID, timestamp, response code, Event ID, and outbox state;
• the first startup or heartbeat failure without credentials or raw payloads.

Route configuration defects to the connector owner and lease or capacity defects to the fleet operator. Route provider-access defects to the Chatwoot account owner, webhook authentication defects to the ingress owner, and uncertain mutations to the Action owner. Escalate cross-tenant output, signature failures, route misbinding, credential exposure, and impossible Event mappings as security or integrity incidents.

Verify recovery

Close the incident only when the corrected path is proven through the normal gateway route, readiness and lease agree, durable Action or Event state is terminal, and no uncertain mutation remains unresolved. Record the evidence and remove temporary containment explicitly.

Related documentation

• Health, observability, and recovery
• Configuration
• Mutation approval and idempotency
• Webhook security, loop prevention, and replay
• Errors and retry decisions