> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formation.texturehq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Generic connector reference

> Understand the existing ingress implementation and unfinished provisioning and delivery paths.

The generic connector is an unfinished integration surface. Inbound decoding,
HMAC authentication, admission limits and an HTTP ingress route are implemented
and tested. **It is not currently a supported end-to-end setup flow:** the
connector catalog marks Webhooks as coming later, the operator API has no generic
connector provisioning endpoint, and production runtime construction does not
wire a generic outbound adapter.

Use [Slack](https://docs.formation.texturehq.com/connectors/slack.md), [Telegram](https://docs.formation.texturehq.com/connectors/telegram.md) or
[phone](https://docs.formation.texturehq.com/connectors/phone.md) for supported conversation setup. Use [remote
MCP](https://docs.formation.texturehq.com/runtime/remote-mcp.md) when you need to give an agent tools; MCP is not the
same interface as sending the agent a conversation message.

The reference below documents the existing inbound implementation for developers.
It does not instruct operators to create database rows by hand or imply that a
registered HTTP route alone can run a complete conversation.

## Inbound wire contract

The route is `POST /generic/events`. Authentication headers are:

| Header | Value |
| - | - |
| `X-Mesh-Install` | Installation routing key |
| `X-Mesh-Timestamp` | Unix seconds, within five minutes of Formation's clock |
| `X-Mesh-Signature` | `v1=<hex HMAC-SHA256>` over `v1:in:{install}:{timestamp}:{raw_body}` |
| `Content-Type` | `application/json` |

The signing secret belongs to the selected installation. The install and the
literal direction tag `in` are included in the signed bytes. The exact raw body
is signed, not a parsed/re-serialized JSON object. An unknown install and a bad
signature receive the same opaque `401`.

```json theme={null}
{
  "message_id": "message-123",
  "conversation_key": "support-case-456",
  "actor_id": "customer-789",
  "actor_display_name": "Customer",
  "body": "Can you explain this result?",
  "body_format": "markdown",
  "topology": "direct",
  "author_is_bot": false
}
```

`message_id`, `conversation_key`, `actor_id` and nonblank `body` are required.
`actor_display_name`, `parent_message_id` and `author_is_bot` are optional.
Empty `body_format` defaults to `markdown`; `text` is also accepted. Empty
`topology` defaults to `direct`; known alternatives are `group` and `channel`.
Unknown topology becomes unknown rather than being trusted as a direct chat.
Unknown JSON fields are tolerated by this decoder.

The connector namespaces the conversation as
`generic:{install}:{conversation_key}`. Caller-supplied conversation keys do not
select another installation's namespace. External participant IDs become actors
within the owning agent's perspective. The bot-author flag is an engagement
signal, not a global actor type.

## Admission and deduplication

The ingress implementation bounds request size, rate-limits incoming sources,
caches unknown installations briefly and caps conversations/actors per install.
It uses the shared durable event-claim mechanism before handing admitted work to
the dispatcher. Tests exercise these boundaries with constructed runtimes; they
do not establish public provisioning or outbound delivery support.

## Work still required

* A supported credential and installation provisioning flow, including rotation
  and disablement.
* Production runtime construction for generic installations.
* Signed outbound delivery and its retry, ordering, idempotency and recovery
  contract. There is no generic persistent delivery outbox today.
* Any optional progress stream or SSE interface.

Earlier design notes described these as a complete webhook product. They were
not evidence that those pieces shipped. The current implementation is in
[`internal/connector/generic`](https://github.com/TextureHQ/formation/tree/main/internal/connector/generic)
and [`internal/app/generic_ingress.go`](https://github.com/TextureHQ/formation/blob/main/internal/app/generic_ingress.go);
production connector construction is in
[`internal/app/wire.go`](https://github.com/TextureHQ/formation/blob/main/internal/app/wire.go).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.