workflow/docs/errors/webhook-invalid-respond-with-value.mdx

Workflow SDK - Build durable, resilient, and observable workflows

---
title: webhook-invalid-respond-with-value
description: The respondWith option must be "manual" or a Response object.
type: troubleshooting
summary: Resolve the webhook-invalid-respond-with-value error by using a valid respondWith option.
prerequisites:
  - /docs/foundations/hooks
related:
  - /docs/api-reference/workflow/create-webhook
---

This error occurs when you provide an invalid value for the `respondWith` option when creating a webhook. The `respondWith` option must be either `"manual"` or a `Response` object.

## Error message

```text
Invalid `respondWith` value: [value]
```

## Why this happens

When creating a webhook with `createWebhook()`, you can specify how the webhook should respond to incoming HTTP requests using the `respondWith` option. This option only accepts specific values:

1. `"manual"` - Allows you to manually send a response from within the workflow
2. A `Response` object - A pre-defined response to send immediately
3. `undefined` (default) - Returns a `202 Accepted` response

## Common causes

### Using an invalid string value

```typescript lineNumbers
// Error - invalid string value
export async function webhookWorkflow() {
  "use workflow";

  const webhook = createWebhook({
    respondWith: "automatic", // Error! // [!code highlight]
  });
}
```

**Solution:** Use `"manual"` or provide a `Response` object.

```typescript lineNumbers
import { createWebhook } from "workflow";

// Fixed - use "manual"
export async function webhookWorkflow() {
  "use workflow";

  const webhook = createWebhook({
    respondWith: "manual", // [!code highlight]
  });

  const request = await webhook;

  // Send custom response
  await request.respondWith(new Response("OK", { status: 200 })); // [!code highlight]
}
```

### Using a non-Response object

```typescript lineNumbers
// Error - plain object instead of Response
export async function webhookWorkflow() {
  "use workflow";

  const webhook = createWebhook({
    respondWith: { status: 200, body: "OK" }, // Error! // [!code highlight]
  });
}
```

**Solution:** Create a proper `Response` object.

```typescript lineNumbers
import { createWebhook } from "workflow";

// Fixed - use Response constructor
export async function webhookWorkflow() {
  "use workflow";

  const webhook = createWebhook({
    respondWith: new Response("OK", { status: 200 }), // [!code highlight]
  });
}
```

## Valid usage examples

### Default behavior (202 response)

```typescript lineNumbers
import { createWebhook } from "workflow";

// Returns 202 Accepted automatically
const webhook = createWebhook();
const request = await webhook;
// No need to send a response
```

### Manual response

```typescript lineNumbers
import { createWebhook } from "workflow";

// Manual response control
const webhook = createWebhook({
  respondWith: "manual",
});

const request = await webhook;

// Process the request...
const data = await request.json();

// Send custom response
await request.respondWith(
  new Response(JSON.stringify({ success: true }), {
    status: 200,
    headers: { "Content-Type": "application/json" },
  })
);
```

### Pre-defined response

```typescript lineNumbers
import { createWebhook } from "workflow";

// Immediate response
const webhook = createWebhook({
  respondWith: new Response("Request received", { status: 200 }),
});

const request = await webhook;
// Response already sent
```

## Learn more

- [createWebhook() API Reference](/docs/api-reference/workflow/create-webhook)
- [resumeWebhook() API Reference](/docs/api-reference/workflow-api/resume-webhook)
- [Webhooks Guide](/docs/foundations/hooks)