# 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"
}
```

## 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)