Clarification on Asynchronous Callback (Webhook) Support for Long-running Workflows

[007long]

Self Checks

• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report (我已阅读并同意 Language Policy).
• [FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:)
• Please do not modify this template :) and fill in all the required fields.

1. Is this request related to a challenge you're experiencing? Tell me about your story.

Dear Dify Support Team,

I am integrating the Dify API into my application and have a specific question regarding handling long-running workflow executions.

1. My Scenario & Problem:

I am using the Workflow App API (as per the /v1/workflows/run endpoint documentation) to execute tasks such as document processing and summarization.

These workflows often take several minutes to complete.

My current approach of using frontend polling (GET /workflows/run/{workflow_run_id}) is not reliable because the frontend connection may timeout or be interrupted before the workflow finishes, causing users to miss the result.

2. My Question:
   Does Dify natively support a callback (webhook) mechanism for its APIs, specifically for the Workflow App? I need a way for Dify to actively notify my server upon workflow completion (success or failure), rather than my application having to continuously poll for status.

3. Key Details from My Research:

The official API documentation for /v1/workflows/run mentions only response_mode: "blocking" or "streaming".

However, I have found community discussions and technical articles suggesting that by setting "response_mode": "async" and providing a "callback_url" parameter in the request body, Dify will send a POST request with the task result to that URL upon completion.

There is also mention of a signature header X-Dify-Signature-V1 for security verification.

Could you please officially confirm:

Is the async + callback_url pattern a supported and stable feature for the Workflow App API?

If yes, are there any official documentation pages or guides detailing its usage, required parameters, and the structure of the callback payload?

If this feature is not available for Workflows, what is the recommended best practice for handling long-running tasks where the client cannot maintain a long-lived connection?

Thank you for your time and assistance. A clarification on this point would greatly help my architecture design.

Best regards,
[Your Name]

2. Additional context or comments

No response

[dosubot[bot]]

Dify's Workflow API does not support asynchronous callbacks or webhooks via response_mode: "async" and callback_url. The /v1/workflows/run endpoint only accepts response_mode values of "blocking" and "streaming", and there is no implementation for webhook or callback logic in the workflow execution code. There are also no references to callback URLs or security headers like X-Dify-Signature-V1 for workflow runs in the codebase or recent pull requests (source).

For long-running workflows, the current best practice is to initiate the workflow and then poll the status using GET /workflows/run/{workflow_run_id} from your backend or a reliable service, rather than relying on the frontend to maintain the connection. This approach helps avoid issues with timeouts or interrupted client sessions. If you need webhook-style notifications, you would need to implement that logic in your own backend as a wrapper around Dify's polling mechanism.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}