Skip to main content
connic

HTTP Webhooks

If a system can send an HTTP request, it can start an agent. Send JSON, form data or files, and get the run IDs or the agent's answer back.

Modes
Inbound, Outbound, Sync
Set up in
Dashboard or connectors/*.yaml
Documentation
HTTP Webhooks docs
Publisher
By connic

Choose what the caller gets back

One connector type covers fire-and-forget events, request and response, and result delivery.

Inbound
connic answers right away with the run IDs and runs every linked agent in the background.
Sync
The request stays open until the agent finishes, and the response carries its output. The default timeout is five minutes.
Outbound
connic POSTs the result to your URL when a run completes, or when the agent or its middleware sends it during the run.
request.sh
curl -X POST <webhook-url> \
  -H "Content-Type: application/json" \
  -H "X-Connic-Secret: <your-secret-key>" \
  -d '{"order_id": "ord_8812", "question": "Where is my order?"}'
inbound-response.json
{
  "status": "ok",
  "dispatched_to": 1,
  "run_ids": ["550e8400-e29b-41d4-a716-446655440000"]
}
sync-response.json
{
  "status": "ok",
  "result": {
    "run_id": "550e8400-e29b-41d4-a716-446655440000",
    "agent_name": "order-assistant",
    "status": "completed",
    "output": "Order ord_8812 shipped on October 12.",
    "error": null
  }
}

Send JSON, form fields or files

The request body becomes the agent's input, and uploaded files go to the model with it.

JSON and form data
A JSON body arrives as sent, form fields become key-value pairs, and a GET passes its query parameters, except the secret.
File uploads
Send multipart/form-data with up to 10 files and 10 MiB in total. The connector accepts images, PDFs, Office documents and data files, and the model reads the formats it supports.
Required files
Turn on Files required on the agent link, and a request without its file fails before the run starts.
upload.sh
curl -X POST <webhook-url> \
  -H "X-Connic-Secret: <your-secret-key>" \
  -F "instructions=What is the total of this invoice?" \
  -F "file=@invoice.pdf"
context["payload"]
{
  "instructions": "What is the total of this invoice?",
  "files": [
    {
      "name": "invoice.pdf",
      "field_name": "file",
      "mime_type": "application/pdf",
      "data": "<base64-bytes>",
      "size": 48213
    }
  ]
}

Keep the webhook next to your agents

Declare it as a YAML file in connectors/. Each deploy creates or updates it for its environment, and a rollback restores it. connic generates the URL and secret, so neither appears in the file.

connectors/order-questions.yaml
type: webhook
mode: sync
name: Order questions
agents:
  - order-assistant
create: connectors/order-questions.yaml (http)

Check every request, sign every delivery

Inbound and sync webhooks require the connector secret by default, and every outbound delivery carries a signature your endpoint can verify.

A secret on every call
Send it as X-Connic-Secret, as a Bearer token or as a secret query parameter. A wrong secret gets a 401, and no run starts.
Signed deliveries
X-Connic-Signature holds an HMAC-SHA256 of the timestamp and the raw body. Reject a delivery whose X-Connic-Timestamp is more than five minutes old.
Private endpoints
Route outbound deliveries through a bridge when the endpoint sits inside your network.
verify_webhook.py
import hashlib
import hmac
import time


def verify_webhook(
    body: bytes, signature: str, timestamp: str, secret: str
) -> bool:
    if abs(time.time() - int(timestamp)) > 300:
        return False
    signed = f"{timestamp}.".encode() + body
    expected = hmac.new(
        secret.encode(), signed, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Where a webhook fits

Pick a setup to see where the request comes from, what it sends and where the result goes.

Your shop backend asks about an order and shows the answer from the same response.

Shop backend
Sync webhook
order-assistant
Answer in the response
order-question.json
{
  "order_id": "ord_8812",
  "question": "Where is my order?"
}
response.json
{
  "status": "ok",
  "result": {
    "run_id": "550e8400-e29b-41d4-a716-446655440000",
    "agent_name": "order-assistant",
    "status": "completed",
    "output": "Order ord_8812 shipped on October 12.",
    "error": null
  }
}

Accounting software uploads each PDF and gets the line items and checked totals back.

Accounting software
Sync webhook
invoice-pipeline
Line items and totals
upload.sh
curl -X POST <webhook-url> \
  -H "X-Connic-Secret: <your-secret-key>" \
  -F "file=@invoice-2041.pdf"
result.output
{
  "valid": true,
  "checks": {
    "tax_matches_rate": true,
    "total_matches_calculation": true,
    "line_total_consistent": true
  },
  "message": "All totals verified"
}

The helpdesk posts each new ticket, and an outbound webhook sends the draft reply back when the run finishes.

Helpdesk
Inbound webhook
support-triage
Draft reply to the helpdesk API
new-ticket.json
{
  "ticket_id": "T-4821",
  "priority": "urgent",
  "subject": "Card charged twice",
  "body": "I was billed twice for my October order."
}
outbound-payload.json
{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_name": "support-triage",
  "status": "completed",
  "output": "Sorry for the double charge. We will refund the second payment.",
  "error": null,
  "started_at": "2026-10-13T09:00:00Z",
  "ended_at": "2026-10-13T09:00:06Z",
  "token_usage": {
    "input_tokens": 812,
    "output_tokens": 64,
    "thinking_tokens": 0,
    "cached_input_tokens": 0,
    "total_tokens": 876
  }
}

Your form tool posts each signup, and an outbound webhook writes the research to your CRM.

Signup form
Inbound webhook
lead-researcher
Research in your CRM
signup.json
{
  "email": "jana@example.com",
  "company": "Example GmbH",
  "plan_interest": "Pro"
}
outbound-payload.json
{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_name": "lead-researcher",
  "status": "completed",
  "output": "Example GmbH: logistics software, 40 people, fits the pro plan.",
  "error": null,
  "started_at": "2026-10-13T09:00:00Z",
  "ended_at": "2026-10-13T09:00:06Z",
  "token_usage": {
    "input_tokens": 812,
    "output_tokens": 64,
    "thinking_tokens": 0,
    "cached_input_tokens": 0,
    "total_tokens": 876
  }
}

HTTP Webhooks FAQ

Add an HTTP Webhook connector to the agent, copy its URL and secret, and send a request. JSON bodies, form data, file uploads and GET query parameters all work. Inbound mode answers with the run IDs while the agent works in the background, and sync mode returns the agent's answer in the same response. For other ways to wire agents, see the common connector patterns.

Inbound and sync webhooks check the connector secret, sent as X-Connic-Secret, as an Authorization: Bearer header or as a secret query parameter. Outbound deliveries are signed with HMAC-SHA256 in X-Connic-Signature and carry X-Connic-Timestamp, so your endpoint can verify them and reject replays.

Yes. Send multipart/form-data with one or more file fields, up to 10 files and 10 MiB in total. Each accepted file goes to the model with the input, and middleware sees the files base64-encoded under the files key of the payload.

Five minutes by default. For longer work, use inbound mode, which answers with the run IDs right away, and let an outbound connector deliver the result when the run finishes.