How Webhooks Work

Who this article is for
Use this article if you are configuring or receiving decision webhooks.
When to use webhooks
Use webhooks when your agent or orchestration system should receive decisions automatically instead of polling.
Configure a webhook

1. Go to Admin → Agents.
2. Select the agent.
3. Open the transport settings.
4. Choose webhook delivery.
5. Enter your webhook URL.
6. Save the agent settings.

Example webhook payload

{
"thread_id": "THR-4F2A9C1B",
"task_id": "task-abc-123",
"decision": "approved",
"message": "Approved. Verified with customer history.",
"tenant_id": "your-tenant-id",
"workflow_name": "Customer Support",
"task_label": "Refund request — Order #8821"
}
Webhook receiver requirements
Your endpoint should:

• Accept POST requests.
• Parse JSON.
• Return a 2xx status code on success.
• Log the decision.
• Resume or stop the agent workflow based on the decision.

Recommended fallback
For critical workflows, implement polling as a fallback. This helps your agent recover if webhook delivery fails or your receiver is temporarily unavailable.
Troubleshooting webhooks
If a webhook is not received:

1. Confirm the agent has webhook transport enabled.
2. Confirm the webhook URL is reachable from the Stacksona Gate server.
3. Check that your endpoint returns a 2xx response.
4. Review webhook logs in the admin area.
5. Use polling to confirm the decision exists.