Webhook Destinations

Webhook Destinations allow external systems to trigger a Mesh Intent by making a simple HTTP POST to a unique URL. They are ideal for event driven or scheduled automation scenarios where you want a Mesh to react autonomously without a human manually starting a conversation.

Quick Reference

Webhook Configuration

Field	Purpose	Guidance
Name	Unique identifier	Short name uniquely identifying the webhook destination.
Description	Usage notes	Description of the webhook destination.
Mesh	Execution graph target	Choose the mesh this webhook will invoke.
Intent	Entry point within mesh	Select intent with appropriate input schema.
Mesh Label	Version snapshot targeting	Specify the version of the mesh to invoke.

Overview

When you create a Webhook Destination you create a new, unique URL that can be used to invoke a mesh.

The resulting URL looks conceptually like:

https://api.partite.ai/webhooks/<unique-key>

Self hosted deployments use your local base URL (for example http://localhost:8080/webhooks/<generated-key>). The caller performs a JSON POST. The body must conform to the Intent input message schema (exact field names, required fields, types, descriptions leveraged for agent context). If validation fails a 4xx error is returned and no conversation is started.

Execution Flow

External system issues POST with JSON body matching the Intent input schema.
Server creates a Conversation and a new top level Request tied to the Intent Agent Version.
The HTTP response returns a lightweight acknowledgement.
The Mesh processes the Request: agents may call tools, sub agents, transfer control, etc. This happens asynchronously to acknowledging receipt of the request.

Use Cases

Event bridging: Forward SaaS webhooks (GitHub issue created, PagerDuty incident, Stripe dispute) into a Mesh for analysis or enrichment.
Scheduled automation: A cron job hits the destination daily to generate a report (Mesh agents fetch data via MCP tools and synthesize structured output).
Data ingestion and classification: Low latency classification of incoming items before they enter a pipeline.
Autonomous follow ups: Trigger a Mesh to draft and send responses, create tickets, or open PRs after external events (ensure separation of capabilities, see Security).

Security Considerations

Webhook Destinations intentionally trade simplicity (just a URL + JSON) for limited built in auth controls:

Concern	Mitigation
URL Guessing	Generated key is high entropy; treat it as a secret. Do not expose in public docs or client side code.
Replay or flood	Optionally place an API gateway or reverse proxy in front to rate limit and log. Consider signing payloads (HMAC) externally before forwarding to the destination.
Untrusted input	Ensure the Intent agent is not simultaneously granted tools that can perform sensitive state changes and access sensitive data (avoid the lethal trifecta). Use a validation or sanitization sub agent via a Call Link before action agents.
Prompt injection	Keep the input schema minimal. Avoid allowing large free form instruction fields unless necessary.
Extraneous data	Reject unneeded fields early. Schema enforcement keeps the prompt small and reduces opportunity for injection.

Operational best practices:

Rotate (regenerate) destination keys if you suspect exposure (delete and recreate the destination).
Maintain an allowlist of source IP addresses at your edge if feasible.
Log request IDs and Mesh label for trace correlation (associate external event ID with Conversation ID).

Versioning Strategy Interaction

Point Webhook Destinations at labeled Mesh versions (prod, staging) to decouple rollout from external integrations. Workflow:

Create destination pointing to staging label.
Send test events; validate outcomes.
Reconfigure (or recreate) destination to point to prod once label updated.

Avoid pointing high volume production webhooks to the Draft Mesh unless actively testing. The Draft may change mid processing.

Summary

Webhook Destinations provide a lightweight, structured bridge from external events into your Mesh. By pairing a unique URL with a strongly typed Intent input schema and a labeled Mesh version you gain predictable invocation, safe evolution (via labels) and clear observability. Keep schemas lean, enforce grounding where accuracy matters, and partition agent capabilities to maintain security.

API Keys