Webhook Configuration & Event Integration

Webhooks in InnoSynth-Forjinn allow your platform to send real-time notifications of events—such as agent completions, flow failures, or dataset updates—to your own systems, automations, chatops, or monitoring tools. Proper webhook setup is essential for event-driven operations, alerting, and advanced integration.

---

What Are Webhooks?

A webhook is an HTTP request (usually POST) sent automatically by Forjinn to an external URL when a specified event occurs. The payload contains event data—e.g., which agent ran, what output was produced, or what error occurred.

---

Supported Events & Use Cases

• flow_completed: Chatflow/workflow finishes a run
• agent_executed: Agent completes (success/fail) or triggers sub-process
• dataset_updated: Data added/changed in a monitored dataset
• evaluation_completed: Evaluation batch run finished
• error_occurred: Exception, crash, or failure (nodes, credentials, tool)

Use Cases:

• Notify Slack/MS Teams/Discord with result summary
• Kick off CI/CD pipeline when model training finished
• Run incident automation on agent failure
• Update dashboards or trigger external workflows (Zapier, custom scripts)

---

Configuring Webhooks

Via UI

1. Go to Settings → API/Webhooks.
2. Click Add Webhook.
3. Enter:
   • URL: Destination to send POST payloads (must be HTTPS in production).
   • Event Type: Pick one or more from the supported list.
   • Secret Key (optional): Used for signature signing/verification.
   • Enabled: Toggle on.
4. Save and test—use "Send Test" to try a sample payload to your webhook.

---

Event Payload & Verification

Example JSON payload for a chatflow completion event:

{
  "event": "flow_completed",
  "timestamp": "2024-06-15T12:00:00Z",
  "id": "flow-run-id-uuid",
  "workspace": "engineering",
  "user": "alice@company.com",
  "chatflowId": "123456",
  "input": "<user input>",
  "output": "<response output>",
  "meta": {
    "duration_ms": 1523,
    "token_usage": 320,
    "node_trace": [...]
  }
}

Signature Verification:
If secret is set, Forjinn will add a signature header:
X-Forjinn-Signature: <hmac-sha256 signature of body>

• On your server, rehash the received body with your secret and compare.

Retries: If your endpoint fails or times out, the platform will retry delivery (default exponential backoff, e.g., up to 5 times over 30m).

---

Advanced Scenarios

• Filter Events: Set up webhooks for specific agents/flows or only error/completion types.
• Multiple Destinations: Register multiple URLs (e.g., Slack, PagerDuty, Google Chat).
• Payload Transformation: Use a relay service (AWS Lambda, Node-RED, Pipedream) to convert to other formats/protocols.
• Trigger Custom Automations: Use with Zapier, Make, or no-code platforms for notifications, tickets, dashboards, etc.

---

Best Practices

• Always use HTTPS and secret/key verification for production.
• Confirm endpoint reliability and idempotency (webhooks may be delivered more than once).
• Log received payloads. Acknowledge quickly (HTTP 2xx), process async if needed.
• Document all registered webhooks and keep endpoints up to date.

---

Troubleshooting

• No payload arrives: Check firewall/SSL/proxy, logs for errors. Use webhook request logs in Forjinn UI.
• Invalid signature: Ensure secret matches and body is unmodified on receive.
• Spam/frequent retries: Your endpoint is slow, failing, or returning non-2xx.

---

Webhooks empower real-time automation, cross-tool integration, and instant notification—be sure to test, monitor, and keep secrets rotated for production use.