# Async and Webhooks

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? <a href="#generate-async-request" id="generate-async-request"></a>

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:

```json
{
  "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? <a href="#verify-webhook-signatures" id="verify-webhook-signatures"></a>

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? <a href="#async-response" id="async-response"></a>

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:

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

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

```json
{
  "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? <a href="#async-validation" id="async-validation"></a>

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:

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

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

## What webhook events does Fetch Hive emit? <a href="#webhook-events" id="webhook-events"></a>

Every webhook delivery has the same envelope:

```json
{
  "event_type": "<event_type>",
  "request_id": "req_...",
  "data": { "...": "..." }
}
```

The `event_type` field tells you which terminal state the workflow reached:

* `workflow.completed` — the workflow finished successfully. `data.output` contains the final output value.
* `workflow.failed` — the workflow errored during execution. `data.error` contains the error message.
* `workflow.cancelled` — the workflow was cancelled before it could complete, either by a user in the Fetch Hive dashboard or directly via the orchestrator. `data.error` contains the cancellation reason, and `data.reason` is always the string `"cancelled"` so you can branch without parsing the message.

Example `workflow.cancelled` payload:

```json
{
  "event_type": "workflow.cancelled",
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "data": {
    "error": "Workflow cancelled: Activity canceled",
    "reason": "cancelled"
  }
}
```

Treat `workflow.cancelled` as a terminal state on your side — no further webhook will be delivered for that `request_id`. The workflow run's partial progress (any completions that finished before the cancel) is still available via the run detail view and the [Logs](https://docs.fetchhive.com/workflows/logs) endpoints.

## Where do I inspect async workflow activity after it starts? <a href="#inspect-async-activity" id="inspect-async-activity"></a>

Use [Logs](https://docs.fetchhive.com/workflows/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](https://docs.fetchhive.com/workflows/run-with-api).

See also: [Run with API](https://docs.fetchhive.com/workflows/run-with-api), [Logs](https://docs.fetchhive.com/workflows/logs), and [Error Handling](https://docs.fetchhive.com/workflows/error-handling)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fetchhive.com/workflows/async-and-webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.