Webhook sessions

When a verified GitHub delivery reaches DataMind Oda, the matching rules can start a new chat from it. This page describes what that chat is, how Oda creates it, and the limits of the webhook flow. The endpoint itself, its settings and the answers it sends are on GitHub webhooks.

What a delivery creates

Every rule that matches the delivery runs, and a rule that returns a request gives Oda what it needs to open a chat:

• An ordinary top-level chat. The chat runs in the folder the rule names, used as its workspace. Its identifier starts with webhook-.
• A recorded notice. The chat's first message is the prompt the rule wrote, recorded as a webhook notice that names the delivery's provider, source, delivery and rule.
• No memory of deliveries. Oda does not skip a delivery it has seen before: repeating a delivery runs the rules again, and can open the chat again. A rule that must act once owns that check itself.

What runs for each delivery

• Every matching rule starts independently. Each rule runs on its own, and one failing rule does not stop the others. A rule can handle a delivery silently, or return one request for a chat; several rules can each return one, so one delivery can create several chats.
• A failing rule is contained. If a rule throws or rejects, the failure is logged for that one run. Oda does not wait for any rule to settle, and nothing about the failure goes back to GitHub.
• Event fields belong to the rule. Oda checks the delivery's envelope before the rules run; what a particular GitHub event must carry is validated by the rule that uses it.
• Rules are checked when they register. Oda refuses a rule with an empty id or kind (webhook rule id must be a non-empty string, webhook rule "<id>" kind must be a non-empty string), an id already in use (webhook rule "<id>" is already registered), a rule without a run function (webhook rule "<id>" requires run()), or a registration while the webhook handling is shutting down (webhook runtime is closing).

How Oda creates the chat

Oda validates the rule's request first, before anything is changed. Then, in order:

1. It resolves the folder the request names as a workspace, registering the folder if it is not one yet.
2. It creates the chat in that folder.
3. It attaches the chat and applies the permission preset the request names.
4. It sets the chat's title and sends the prompt as the first message.

Accepting the prompt is where the creation settles: before that point, a failure leaves no chat behind. A chat that was already attached is detached and disposed when an attempt is rolled back, and a workspace registered for the attempt can stay behind. Rollbacks are best effort.

What the 202 answer means

GitHub gets its 202 as soon as the verified payload was dispatched in memory. The answer comes before the rules run: it does not say that a rule matched, or that a chat was created. The full set of answers is on GitHub webhooks.

Reliability limits

• In memory, fire and forget. Handling happens inside Oda. A crash loses the rule calls that had not yet reached a prompt; there is no queue, replay or retry behind them.
• No completion result. Accepting a delivery and settling a rule do not report whether the chat succeeded, went idle or produced output. Read the chat for what happened.
• Cancellation is cooperative. When the webhook handling shuts down, Oda hides the rules, aborts their runs and waits for the callbacks, but a rule must answer the cancellation signal itself; Oda cannot stop arbitrary code inside it.
• A workspace can outlive a failed attempt. If the attempt failed after registering a folder as a workspace, the empty workspace stays, because another caller may already be using it.

When something is refused

These refusals are reported as messages rather than shown in the chat. Each message names the rule or the chat it belongs to.

• The delivery. Before a rule runs, the delivery is checked: its kind, source and id must be non-empty (webhook delivery kind must be a non-empty string, webhook delivery source must be a non-empty string, webhook delivery id must be a non-empty string), its receipt time must be a non-negative whole number (webhook delivery receivedAt must be a non-negative safe integer), and its payload must be lossless JSON (webhook delivery must be lossless JSON).
• The rule's result. A rule must return nothing or a single request: webhook rule result must be null or a Session request object.
• The request. Every required text value must be non-empty (webhook Session request <field> must be a non-empty string), the folder must be an absolute path (webhook Session request workspacePath must be absolute, got "<path>"), and a model, when named, must be an object whose token cap, when set, is a positive whole number (webhook Session request model must be an object, webhook Session request model.maxTokens must be a positive safe integer).
• The chat's folder and its workspace. When a webhook message enters a chat, Oda checks that the chat's recorded folder matches exactly one workspace. The check fails with webhook Session "<id>" has no cwd, webhook Session "<id>" belongs to <n> Workspaces at prompt admission, or webhook Session "<id>" cwd <cwd> differs from its Workspace path.

What the log keeps

Each run records a line naming its provider, source, delivery and rule, in the shape webhook: provider=... source=... delivery=... rule=...; a rule that fails adds the reason after failed:.

Questions, answered

Where does a chat created by a webhook appear?

It is an ordinary top-level chat, so you open it like any other chat. It belongs to the workspace the rule named, its identifier starts with webhook-, and its first message is the rule's prompt, recorded as a webhook notice.

Why did the same event create a second chat?

Nothing deduplicates deliveries. Oda runs the rules again for every delivery, including one it has handled before, so a second delivery can open a second chat. If a rule must act once, the rule owns that check; the delivery's identifier is recorded on the message so the rule can use it.

Does the 202 answer mean a chat was created?

No. It means only that the verified payload was dispatched in memory. It comes before the rules run and says nothing about rule matches or chats. See GitHub webhooks.

What happens when one rule fails?

The failure is logged for that run only. The other rules still run, and nothing about the failure goes back to GitHub.

Which folder does a webhook chat run in?

The folder the rule's request names, given as an absolute path. If that folder is not a workspace yet, Oda registers it as one. The chat then works there like any chat in its workspace (Workspaces, files and permissions).

Can one delivery create more than one chat?

Yes. Every matching rule runs on its own, and each rule can return one request, so several rules can each open a chat from the same delivery.

How do I know whether a webhook chat finished its work?

There is no completion result. Accepting the delivery and settling a rule do not report whether the chat succeeded, went idle or produced output, so open the chat and read what it did.

Which model does a webhook chat use?

A rule may name the chat's model and an output-token cap. When it names none, the chat starts with Oda's default model selection.

What happens if Oda is closed while a delivery is being handled?

Handling is in memory and fire and forget. A rule call that had not yet reached a prompt is lost, and nothing queues, replays or retries it. A workspace registered for the attempt can stay behind.

What does Oda add to the chat's first message?

The message text is the prompt exactly as the rule wrote it. Oda adds no framing of its own; the message is marked as a webhook notice so you can tell where it came from.