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.
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?"}'{
"status": "ok",
"dispatched_to": 1,
"run_ids": ["550e8400-e29b-41d4-a716-446655440000"]
}{
"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.
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"{
"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.
type: webhook
mode: sync
name: Order questions
agents:
- order-assistantCheck 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.
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.
{
"order_id": "ord_8812",
"question": "Where is my order?"
}{
"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.
curl -X POST <webhook-url> \
-H "X-Connic-Secret: <your-secret-key>" \
-F "file=@invoice-2041.pdf"{
"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.
{
"ticket_id": "T-4821",
"priority": "urgent",
"subject": "Card charged twice",
"body": "I was billed twice for my October order."
}{
"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.
{
"email": "jana@example.com",
"company": "Example GmbH",
"plan_interest": "Pro"
}{
"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
More connectors
AWS SQS
Drain SQS queues with an agent. Each message is deleted once its runs complete, and failed ones return after the visibility timeout.
Inbound · Outbound
Google Pub/Sub
Run an agent on every message a Pub/Sub push subscription delivers, checked with Google's signed token, and publish results to a topic.
Inbound · Outbound
Jira
Run an agent on new issues, issue updates and comments in Jira Cloud. It comments back or creates a new issue.
Inbound · Outbound
Linear
Run an agent on new and updated issues and comments in a Linear team. It replies in the comment thread or creates a new issue.
Inbound · Outbound
SIP Voice
Answer and place calls with a voice agent on any phone system or provider that supports SIP. Transfer callers and queue them while the agent is busy.
Sync · Outbound
WhatsApp
Answer WhatsApp messages to your business number with an agent, files included. Reply within 24 hours or reach people with approved templates.
Inbound · Outbound