Webhook / API Channel

How It Works

1. You connect a Webhook / API channel and get a unique endpoint URL scoped to this agent.
2. An external service POSTs a JSON body to that URL.
3. Communa verifies the request (based on your chosen auth mode and the credential you entered), then returns 202 Accepted right away.
4. The agent processes the payload in the background — using the same tools, skills, and context as dashboard chat.

Because the response is immediate and async, this works cleanly for long-running agent jobs. There is no synchronous reply body; the agent acts on the payload (sends emails, updates datasets, calls integrations, etc.).

---

Connecting a Webhook

1. Go to your agent → Channels tab
2. Click Connect Channel → select Webhook
3. Choose an Authentication mode and enter the credential your calling service will send (see below)
4. Click Create Webhook
5. Copy the Endpoint URL — then start POSTing with the credential you entered

---

Authentication Modes

For Bearer, Header and Basic modes, always serve your endpoint over HTTPS — the credential travels on the wire.

For Signature (HMAC) mode the signature is computed as HMAC-SHA256(secret, "<timestamp>.<raw_body>") and the timestamp must be within a few minutes of server time (replay protection). The secret is generated by Communa and shown once.

For Provider signature mode you supply the provider's signing secret, the header name they use, and the scheme (hex, base64, or Stripe-style timestamped).

---

Payload Shapes

The webhook accepts either of these:

1. A natural-language message

jsonCopy
{ "message": "Summarize today's new signups and email me the report" }

Auto-detected fields: message, text, or prompt. You can also set a custom Message Field dot-path (e.g. input.message) in the setup drawer.

2. Structured fields

jsonCopy
{
  "event": "order.created",
  "order_id": "ord_123",
  "amount": 4999,
  "customer_email": "jane@acme.com"
}

When there is no message field, the entire payload is passed to the agent as a structured trigger block. You tell the agent how to interpret it via handling instructions (below).

The full raw payload is always preserved and available to the agent, regardless of which shape you send.

---

Handling Instructions

Just like the Mail channel, you can give the agent custom webhook handling instructions so it knows what to do with each incoming trigger.

1. Go to your agent → Settings → Webhook / API
2. Write instructions in plain language, for example:

3. Save. These instructions are injected into the agent's context on every webhook trigger.

The agent can also update its own webhook handling instructions when you ask it to during a chat.

---

Examples

Bearer token

Use the token you entered when connecting.

bashCopy
curl -X POST https://app.communa.io/api/webhooks/agent/<connection-id> \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Draft a weekly summary and email it to me" }'

Header auth + structured payload

You choose both the header name (e.g. X-API-Key) and its value when connecting.

bashCopy
curl -X POST https://app.communa.io/api/webhooks/agent/<connection-id> \
  -H "X-API-Key: <your-value>" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "lead.created",
    "name": "Jane Doe",
    "email": "jane@acme.com",
    "company": "Acme Inc"
  }'

Basic auth

Use the username and password you entered when connecting.

bashCopy
curl -X POST https://app.communa.io/api/webhooks/agent/<connection-id> \
  -u "<your-username>:<your-password>" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Process the new order" }'

Signature (HMAC) — advanced

bashCopy
# Compute the signature over "<timestamp>.<raw_body>"
TS=$(date +%s)
BODY='{"message":"Process the new lead"}'
SIG=$(printf "%s.%s" "$TS" "$BODY" | openssl dgst -sha256 -hmac "<your-secret>" | awk '{print $2}')

curl -X POST https://app.communa.io/api/webhooks/agent/<connection-id> \
  -H "X-Communa-Signature: t=$TS,v1=$SIG" \
  -H "Content-Type: application/json" \
  -d "$BODY"

Expected response

jsonCopy
{ "accepted": true }

The endpoint returns 202 Accepted immediately. The agent runs asynchronously — track progress in the agent's Runs tab.

---

Tips & Best Practices

• Always use HTTPS — Bearer, Header and Basic modes send the credential on the wire. Signed (HMAC) never sends the secret, so it's the strongest option for backends you control.
• Avoid "None" in production — it relies only on the secret URL and offers no request integrity.
• Keep payloads reasonable — very large bodies are rejected. Send only the fields the agent needs.
• Write clear handling instructions — the more specific your Settings → Webhook / API instructions, the more reliable the agent's behavior.
• Watch the Runs tab — since responses are async, use Runs to confirm the agent received and processed each trigger.
• Rotate a leaked credential — disconnect and reconnect the channel with a new credential.

What's Next?

• Channels Overview — Shared channel features, attachments, auto-wake, and connection management
• Telegram Channel — Connect your agent via a Telegram bot
• Mail — Give your agent its own email address with handling instructions
• API Overview — The full HTTP API for datasets and more