Debugging#

Outeract is event-driven, and almost everything it does leaves a queryable trace: events, graph edges, logs, and webhook delivery records. This page tours the tools you’ll reach for when something misbehaves.

GraphiQL: the API in your browser#

The API root serves GraphiQL, an in-browser IDE for the GraphQL API:

Open https://api.outeract.com/
Add your key in the headers panel: {"Authorization": "Bearer YOUR_API_KEY"}
Explore the schema via the docs sidebar (introspection works without extra setup) and run queries live.

GraphiQL is the fastest way to find out what a field actually returns, and its schema documentation is generated from the running server, so it’s never stale.

The console event stream#

The console shows a live event stream per application (Events). Because every domain action (inbound message, outbound message, file upload, delivery failure) is an event, the stream doubles as a live debugger:

Watch it while you reproduce a problem: send a test message and confirm the message.inbound event appears. If it doesn’t, the problem is upstream (platform webhook not firing); if it does, the problem is downstream (your webhook subscription or handler).
Open any event to inspect its full JSON payload and its edges.

The same data is available programmatically:

query {
  events(eventType: "message.inbound", limit: 10) {
    id
    eventType
    payload
    createdAt
  }
}

Tracing a message end-to-end with edges#

Every event is linked to related entities by graph edges: sent_by, sent_to, in_conversation, attachment, participant. This gives you a built-in audit trail. To trace a message:

query {
  event(id: "EVENT_ID") {
    id
    eventType
    payload
    edges {
      edgeType
      targetNodeType
      targetNodeId
    }
  }
}

From a message event you can walk to the sending user, the recipient, the conversation, and any attached files. Going the other direction, the events query supports edge-target filters (relatedNodeId, relatedNodeType, relatedEdgeType), so you can pull every event touching a given user or conversation:

query {
  events(relatedNodeId: "USER_ID", relatedNodeType: "user", limit: 50) {
    id eventType createdAt
  }
}

Typical end-to-end trace for “the reply never arrived”:

Find the inbound event (message.inbound), which confirms the platform webhook reached Outeract.
Follow its in_conversation edge, then list events in that conversation, which confirms your outbound sendMessage created a message.outbound event.
Check the outbound event’s payload for delivery_status; failed_at and error_type tell you why the platform rejected it.
Check logs(eventId: ...) for processing details (next section).

Logs#

The logs query returns server-side log entries for your application, and can be filtered to the logs attached to specific events:

query {
  logs(eventId: "EVENT_ID", limit: 100) {
    id
    logLevel
    logType
    message
    createdAt
  }
}

Useful filters:

logLevel: "error": only errors (levels: debug, info, warning, error)
logType: e.g. webhook_error, webhook_retry, execution
eventIds: [...]: batch-fetch logs for many events at once

A quick “anything on fire?” sweep is logs(logLevel: "error", limit: 50).

Webhook delivery debugging#

Outbound webhooks are the most common integration pain point, so they get the deepest tooling.

These live on the subscription’s detail page in the console, under Settings → Webhooks.

Send a test delivery to verify your endpoint and signature handling without waiting for a real event. The test request is signed exactly like a real delivery (X-Outeract-Signature, X-Outeract-Event-Type: webhook.test), so it exercises your verification code, and the result reports the status code, response time and any error.

Inspect delivery attempts. Every delivery records the response status, error message, attempt count, and timing.

Aggregate health and timing. Success/failure counts plus response-time charts over time, which is how you spot a slowly degrading endpoint before it starts timing out.

Failed deliveries are retried up to the subscription’s max attempts (default 5) with a configurable backoff, and each retry is logged with logType: "webhook_retry".

Platform connection health#

When sends fail or inbound messages stop, check the connection itself: open it in the console and run a health check.

The health check runs individual tests (credential validation, webhook registration status, API quota), so the failing test tells you which layer broke. The connection setup flow can also test credentials before saving them, and Reconnect Webhook re-registers the platform-side webhook for platforms that support auto-setup.

Not every platform supports health checks; the console only offers the action on platforms that declare the capability.

Local testing tips#

There is no verbose/debug response flag; the logs query and webhook delivery records are the intended diagnostic surface.
Use ngrok or similar to expose your local webhook handler to Outeract when testing subscriptions end-to-end.