> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Parallel webhooks

> Parallel incoming webhooks in Corsair: the event paths to subscribe to, the payload each event carries, and the response data.

The Parallel plugin handles incoming webhooks. Point your provider’s subscription URL at your Corsair HTTP handler (see [Overview](https://docs.corsair.dev/plugins/parallel/overview.md) for setup context and the exact URL shape).

> [!NOTE]
>
> **New to Corsair?** See [webhooks](https://docs.corsair.dev/concepts/webhooks.md) and [hooks](https://docs.corsair.dev/concepts/hooks.md).

## Webhook map

* `findall`
  * `candidateEnriched` (`findall.candidateEnriched`)
  * `candidateGenerated` (`findall.candidateGenerated`)
  * `candidateMatched` (`findall.candidateMatched`)
  * `runCancelled` (`findall.runCancelled`)
  * `runCompleted` (`findall.runCompleted`)
  * `runFailed` (`findall.runFailed`)
* `monitor`
  * `eventDetected` (`monitor.eventDetected`)
  * `executionCompleted` (`monitor.executionCompleted`)
  * `executionFailed` (`monitor.executionFailed`)
* `taskRun`
  * `status` (`taskRun.status`)

## HTTP handler setup

```ts app/api/webhook/route.ts theme={null}
import { processWebhook } from "corsair";
import { corsair } from "@/server/corsair";

export async function POST(request: Request) {
    const headers = Object.fromEntries(request.headers);
    // With multiTenancy, give each tenant its own URL (/api/webhook?tenantId=acme):
    // the query says whose account, secret and hooks handle the delivery.
    const query = Object.fromEntries(new URL(request.url).searchParams);
    // The raw text, not request.json(): signatures are checked over the exact bytes sent.
    const body = await request.text();
    const result = await processWebhook(corsair, headers, body, query);
    if (!result.plugin) {
        return Response.json({ success: false }, { status: 404 });
    }
    // A refusal (bad signature) carries no status and answers 400; a handler
    // that threw comes back with 500, so the sender retries it.
    const status =
        result.response?.success === false ? (result.response.statusCode ?? 400) : 200;
    return Response.json(result.response ?? { success: true }, {
        status,
        headers: result.responseHeaders,
    });
}
```

## Events

## Findall

### Candidate Enriched

`findall.candidateEnriched`

Enrichment data was extracted for a FindAll candidate

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `type` | `findall.candidate.enriched` | Yes | — |
| `timestamp` | `string` | Yes | — |
| `data` | `object` | Yes | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   candidate_id: string,
>   name: string,
>   url: string,
>   match_status: generated | matched | unmatched | discarded | string,
>   description?: string | null,
>   output?: Record<string, JsonValue> | null,
>   basis?: {
>     field: string,
>     reasoning: string,
>     confidence?: string | null,
>     citations?: {
>       url: string,
>       title?: string | null,
>       excerpts?: string[] | null
>     }[]
>   }[] | null,
>   findall_id: string
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   type: findall.candidate.enriched,
>   timestamp: string,
>   data: {
>     candidate_id: string,
>     name: string,
>     url: string,
>     match_status: generated | matched | unmatched | discarded | string,
>     description?: string | null,
>     output?: Record<string, JsonValue> | null,
>     basis?: {
>       field: string,
>       reasoning: string,
>       confidence?: string | null,
>       citations?: {
>         url: string,
>         title?: string | null,
>         excerpts?: string[] | null
>       }[]
>     }[] | null,
>     findall_id: string
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
parallel({
    webhookHooks: {
        findall: {
            candidateEnriched: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Candidate Generated

`findall.candidateGenerated`

A FindAll run found a candidate and queued it for checking

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `type` | `findall.candidate.generated` | Yes | — |
| `timestamp` | `string` | Yes | — |
| `data` | `object` | Yes | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   candidate_id: string,
>   name: string,
>   url: string,
>   match_status: generated | matched | unmatched | discarded | string,
>   description?: string | null,
>   output?: Record<string, JsonValue> | null,
>   basis?: {
>     field: string,
>     reasoning: string,
>     confidence?: string | null,
>     citations?: {
>       url: string,
>       title?: string | null,
>       excerpts?: string[] | null
>     }[]
>   }[] | null,
>   findall_id: string
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   type: findall.candidate.generated,
>   timestamp: string,
>   data: {
>     candidate_id: string,
>     name: string,
>     url: string,
>     match_status: generated | matched | unmatched | discarded | string,
>     description?: string | null,
>     output?: Record<string, JsonValue> | null,
>     basis?: {
>       field: string,
>       reasoning: string,
>       confidence?: string | null,
>       citations?: {
>         url: string,
>         title?: string | null,
>         excerpts?: string[] | null
>       }[]
>     }[] | null,
>     findall_id: string
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
parallel({
    webhookHooks: {
        findall: {
            candidateGenerated: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Candidate Matched

`findall.candidateMatched`

A FindAll candidate met every match condition

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `type` | `findall.candidate.matched` | Yes | — |
| `timestamp` | `string` | Yes | — |
| `data` | `object` | Yes | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   candidate_id: string,
>   name: string,
>   url: string,
>   match_status: generated | matched | unmatched | discarded | string,
>   description?: string | null,
>   output?: Record<string, JsonValue> | null,
>   basis?: {
>     field: string,
>     reasoning: string,
>     confidence?: string | null,
>     citations?: {
>       url: string,
>       title?: string | null,
>       excerpts?: string[] | null
>     }[]
>   }[] | null,
>   findall_id: string
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   type: findall.candidate.matched,
>   timestamp: string,
>   data: {
>     candidate_id: string,
>     name: string,
>     url: string,
>     match_status: generated | matched | unmatched | discarded | string,
>     description?: string | null,
>     output?: Record<string, JsonValue> | null,
>     basis?: {
>       field: string,
>       reasoning: string,
>       confidence?: string | null,
>       citations?: {
>         url: string,
>         title?: string | null,
>         excerpts?: string[] | null
>       }[]
>     }[] | null,
>     findall_id: string
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
parallel({
    webhookHooks: {
        findall: {
            candidateMatched: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Run Cancelled

`findall.runCancelled`

A FindAll run was cancelled

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `type` | `findall.run.cancelled` | Yes | — |
| `timestamp` | `string` | Yes | — |
| `data` | `object` | Yes | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   findall_id: string,
>   generator: base | core | pro | preview | string,
>   status: {
>     status: queued | action_required | running | completed | failed | cancelling | cancelled | string,
>     is_active: boolean,
>     metrics: {
>       generated_candidates_count?: number,
>       matched_candidates_count?: number
>     },
>     termination_reason?: low_match_rate | match_limit_met | candidates_exhausted | user_cancelled | error_occurred | timeout | insufficient_funds | string | null
>   },
>   metadata?: Record<string, string | number | boolean> | null,
>   created_at?: string | null,
>   modified_at?: string | null
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   type: findall.run.cancelled,
>   timestamp: string,
>   data: {
>     findall_id: string,
>     generator: base | core | pro | preview | string,
>     status: {
>       status: queued | action_required | running | completed | failed | cancelling | cancelled | string,
>       is_active: boolean,
>       metrics: {
>         generated_candidates_count?: number,
>         matched_candidates_count?: number
>       },
>       termination_reason?: low_match_rate | match_limit_met | candidates_exhausted | user_cancelled | error_occurred | timeout | insufficient_funds | string | null
>     },
>     metadata?: Record<string, string | number | boolean> | null,
>     created_at?: string | null,
>     modified_at?: string | null
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
parallel({
    webhookHooks: {
        findall: {
            runCancelled: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Run Completed

`findall.runCompleted`

A FindAll run completed

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `type` | `findall.run.completed` | Yes | — |
| `timestamp` | `string` | Yes | — |
| `data` | `object` | Yes | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   findall_id: string,
>   generator: base | core | pro | preview | string,
>   status: {
>     status: queued | action_required | running | completed | failed | cancelling | cancelled | string,
>     is_active: boolean,
>     metrics: {
>       generated_candidates_count?: number,
>       matched_candidates_count?: number
>     },
>     termination_reason?: low_match_rate | match_limit_met | candidates_exhausted | user_cancelled | error_occurred | timeout | insufficient_funds | string | null
>   },
>   metadata?: Record<string, string | number | boolean> | null,
>   created_at?: string | null,
>   modified_at?: string | null
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   type: findall.run.completed,
>   timestamp: string,
>   data: {
>     findall_id: string,
>     generator: base | core | pro | preview | string,
>     status: {
>       status: queued | action_required | running | completed | failed | cancelling | cancelled | string,
>       is_active: boolean,
>       metrics: {
>         generated_candidates_count?: number,
>         matched_candidates_count?: number
>       },
>       termination_reason?: low_match_rate | match_limit_met | candidates_exhausted | user_cancelled | error_occurred | timeout | insufficient_funds | string | null
>     },
>     metadata?: Record<string, string | number | boolean> | null,
>     created_at?: string | null,
>     modified_at?: string | null
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
parallel({
    webhookHooks: {
        findall: {
            runCompleted: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Run Failed

`findall.runFailed`

A FindAll run failed

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `type` | `findall.run.failed` | Yes | — |
| `timestamp` | `string` | Yes | — |
| `data` | `object` | Yes | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   findall_id: string,
>   generator: base | core | pro | preview | string,
>   status: {
>     status: queued | action_required | running | completed | failed | cancelling | cancelled | string,
>     is_active: boolean,
>     metrics: {
>       generated_candidates_count?: number,
>       matched_candidates_count?: number
>     },
>     termination_reason?: low_match_rate | match_limit_met | candidates_exhausted | user_cancelled | error_occurred | timeout | insufficient_funds | string | null
>   },
>   metadata?: Record<string, string | number | boolean> | null,
>   created_at?: string | null,
>   modified_at?: string | null
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   type: findall.run.failed,
>   timestamp: string,
>   data: {
>     findall_id: string,
>     generator: base | core | pro | preview | string,
>     status: {
>       status: queued | action_required | running | completed | failed | cancelling | cancelled | string,
>       is_active: boolean,
>       metrics: {
>         generated_candidates_count?: number,
>         matched_candidates_count?: number
>       },
>       termination_reason?: low_match_rate | match_limit_met | candidates_exhausted | user_cancelled | error_occurred | timeout | insufficient_funds | string | null
>     },
>     metadata?: Record<string, string | number | boolean> | null,
>     created_at?: string | null,
>     modified_at?: string | null
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
parallel({
    webhookHooks: {
        findall: {
            runFailed: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

## Monitor

### Event Detected

`monitor.eventDetected`

A monitor run detected one or more events

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `type` | `monitor.event.detected` | Yes | — |
| `timestamp` | `string` | Yes | — |
| `data` | `object` | Yes | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   monitor_id: string,
>   event: {
>     event_group_id: string
>   },
>   metadata?: Record<string, string | number | boolean> | null
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   type: monitor.event.detected,
>   timestamp: string,
>   data: {
>     monitor_id: string,
>     event: {
>       event_group_id: string
>     },
>     metadata?: Record<string, string | number | boolean> | null
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
parallel({
    webhookHooks: {
        monitor: {
            eventDetected: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Execution Completed

`monitor.executionCompleted`

A monitor run completed without detecting events

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `type` | `monitor.execution.completed` | Yes | — |
| `timestamp` | `string` | Yes | — |
| `data` | `object` | Yes | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   monitor_id: string,
>   event: {
>     type?: string,
>     monitor_ts?: string | null
>   },
>   metadata?: Record<string, string | number | boolean> | null
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   type: monitor.execution.completed,
>   timestamp: string,
>   data: {
>     monitor_id: string,
>     event: {
>       type?: string,
>       monitor_ts?: string | null
>     },
>     metadata?: Record<string, string | number | boolean> | null
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
parallel({
    webhookHooks: {
        monitor: {
            executionCompleted: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Execution Failed

`monitor.executionFailed`

A monitor run failed

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `type` | `monitor.execution.failed` | Yes | — |
| `timestamp` | `string` | Yes | — |
| `data` | `object` | Yes | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   monitor_id: string,
>   event: {
>     type?: string,
>     error?: string | null,
>     id?: string | null,
>     date?: string | null
>   },
>   metadata?: Record<string, string | number | boolean> | null
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   type: monitor.execution.failed,
>   timestamp: string,
>   data: {
>     monitor_id: string,
>     event: {
>       type?: string,
>       error?: string | null,
>       id?: string | null,
>       date?: string | null
>     },
>     metadata?: Record<string, string | number | boolean> | null
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
parallel({
    webhookHooks: {
        monitor: {
            executionFailed: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

## Task Run

### Status

`taskRun.status`

A task run finished, successfully or not

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `type` | `task_run.status` | Yes | — |
| `timestamp` | `string` | Yes | — |
| `data` | `object` | Yes | — |

> [accordion] data full type
>
> ```ts theme={null}
> {
>   run_id: string,
>   interaction_id: string,
>   status: queued | action_required | running | completed | failed | cancelling | cancelled | string,
>   is_active: boolean,
>   processor: string,
>   created_at: string | null,
>   modified_at: string | null,
>   warnings?: {
>     type: string,
>     message: string,
>     detail?: Record<string, any> | null
>   }[] | null,
>   error?: {
>     message: string,
>     ref_id?: string,
>     detail?: Record<string, JsonValue> | null,
>     details?: string | JsonValue | null
>   } | null,
>   metadata?: Record<string, string | number | boolean> | null,
>   taskgroup_id?: string | null
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   type: task_run.status,
>   timestamp: string,
>   data: {
>     run_id: string,
>     interaction_id: string,
>     status: queued | action_required | running | completed | failed | cancelling | cancelled | string,
>     is_active: boolean,
>     processor: string,
>     created_at: string | null,
>     modified_at: string | null,
>     warnings?: {
>       type: string,
>       message: string,
>       detail?: Record<string, any> | null
>     }[] | null,
>     error?: {
>       message: string,
>       ref_id?: string,
>       detail?: Record<string, JsonValue> | null,
>       details?: string | JsonValue | null
>     } | null,
>     metadata?: Record<string, string | number | boolean> | null,
>     taskgroup_id?: string | null
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
parallel({
    webhookHooks: {
        taskRun: {
            status: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.