Async and Webhooks

Run a workflow asynchronously, send the result to a callback URL, and verify signed webhook delivery

Use async workflow invocation when you do not want your app to wait for the full workflow to finish in the same HTTP request. Instead of waiting for the final output, you send a callback URL and let Fetch Hive deliver the result later by webhook.

Overview

The current workflow invoke UI exposes async mode in the Invoke a Workflow Deployment dialog. When you turn on Async, the generated cURL snippet adds an async object with enabled and callback_url.

The same UI also exposes a Signing secret and tells you to verify the X-Fetch-Hive-Signature header with HMAC SHA256. Use that secret to confirm that webhook events came from Fetch Hive.

How do I generate an async workflow invoke request?

Open More in the workflows sidebar and click Get Code, or open Code Snippet from a workflow deployment page.

Select the Deployment and Variant you want to invoke.

Turn on Async.

The cURL snippet updates to include:

{
  "async": {
    "enabled": true,
    "callback_url": "https://example.com/callback"
  }
}

Replace the example callback URL with your real webhook endpoint before you run the request.

How do I verify webhook signatures?

Turn on Async in the code snippet dialog.

Copy the Signing secret shown below the snippet, or view the same secret from the workflow deployment details page.

When your server receives the webhook, verify the X-Fetch-Hive-Signature header using HMAC SHA256 and that signing secret.

Treat any webhook that fails signature verification as untrusted.

What response do I get from an async workflow invoke?

When async mode is enabled, the public route returns immediately instead of waiting for the workflow output.

The current public route can return a running state:

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "running",
  "webhook_secret": "YOUR_WEBHOOK_SECRET"
}

At high concurrency, it can also return a queued state:

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "queued",
  "webhook_secret": "YOUR_WEBHOOK_SECRET"
}

Use the returned request_id for your own request tracking, and rely on webhook delivery for the final result flow.

What validation rules apply to async mode?

If async.enabled is true, callback_url is required.

The current public route also validates that callback_url is a valid URL.

For example, these errors are explicitly confirmed:

{
  "error": "callback_url is required when async is enabled"
}

{
  "error": "callback_url must be a valid URL"
}

Where do I inspect async workflow activity after it starts?

Use Logs after the workflow starts.

The workflow run detail view can show the Async badge, Async Configuration, output, and Webhook Logs for runs that used async delivery.

If webhook delivery fails, the logs view can also show retry history and response details for each webhook attempt.

Async workflow notes

Async invocation and signed webhook delivery are separate parts of the same flow. The invoke request starts the run and returns quickly. The webhook is how the final result reaches your callback URL later.

If you do not need delayed delivery, keep async disabled and use the normal synchronous response documented in Run with API.

See also: Run with API, Logs, and Error Handling