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

# SignWell webhooks

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

The SignWell plugin handles incoming webhooks. Point your provider’s subscription URL at your Corsair HTTP handler (see [Overview](https://docs.corsair.dev/plugins/signwell/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

* `document`
  * `canceled` (`document.canceled`)
  * `completed` (`document.completed`)
  * `created` (`document.created`)
  * `declined` (`document.declined`)
  * `expired` (`document.expired`)
  * `inProgress` (`document.inProgress`)
  * `recipientsUpdated` (`document.recipientsUpdated`)
  * `sent` (`document.sent`)
  * `signed` (`document.signed`)
  * `viewed` (`document.viewed`)

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

## Document

### Canceled

`document.canceled`

The sender canceled the document.

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `event` | `object` | Yes | — |
| `data` | `object` | Yes | — |

> [accordion] event full type
>
> ```ts theme={null}
> {
>   hash: string,
>   time: number,
>   type: string,
>   related_signer?: {
>     email?: string | null,
>     name?: string | null
>   } | null
> }
> ```

> [accordion] data full type
>
> ```ts theme={null}
> {
>   object: Record<string, any>
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   event: {
>     hash: string,
>     time: number,
>     type: string,
>     related_signer?: {
>       email?: string | null,
>       name?: string | null
>     } | null
>   },
>   data: {
>     object: Record<string, any>
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
signwell({
    webhookHooks: {
        document: {
            canceled: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Completed

`document.completed`

Every recipient signed and the document is complete.

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `event` | `object` | Yes | — |
| `data` | `object` | Yes | — |

> [accordion] event full type
>
> ```ts theme={null}
> {
>   hash: string,
>   time: number,
>   type: string,
>   related_signer?: {
>     email?: string | null,
>     name?: string | null
>   } | null
> }
> ```

> [accordion] data full type
>
> ```ts theme={null}
> {
>   object: Record<string, any>
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   event: {
>     hash: string,
>     time: number,
>     type: string,
>     related_signer?: {
>       email?: string | null,
>       name?: string | null
>     } | null
>   },
>   data: {
>     object: Record<string, any>
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
signwell({
    webhookHooks: {
        document: {
            completed: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Created

`document.created`

A document was created.

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `event` | `object` | Yes | — |
| `data` | `object` | Yes | — |

> [accordion] event full type
>
> ```ts theme={null}
> {
>   hash: string,
>   time: number,
>   type: string,
>   related_signer?: {
>     email?: string | null,
>     name?: string | null
>   } | null
> }
> ```

> [accordion] data full type
>
> ```ts theme={null}
> {
>   object: Record<string, any>
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   event: {
>     hash: string,
>     time: number,
>     type: string,
>     related_signer?: {
>       email?: string | null,
>       name?: string | null
>     } | null
>   },
>   data: {
>     object: Record<string, any>
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
signwell({
    webhookHooks: {
        document: {
            created: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Declined

`document.declined`

A recipient declined to sign.

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `event` | `object` | Yes | — |
| `data` | `object` | Yes | — |

> [accordion] event full type
>
> ```ts theme={null}
> {
>   hash: string,
>   time: number,
>   type: string,
>   related_signer?: {
>     email?: string | null,
>     name?: string | null
>   } | null
> }
> ```

> [accordion] data full type
>
> ```ts theme={null}
> {
>   object: Record<string, any>
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   event: {
>     hash: string,
>     time: number,
>     type: string,
>     related_signer?: {
>       email?: string | null,
>       name?: string | null
>     } | null
>   },
>   data: {
>     object: Record<string, any>
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
signwell({
    webhookHooks: {
        document: {
            declined: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Expired

`document.expired`

The document passed its expiry date without being completed.

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `event` | `object` | Yes | — |
| `data` | `object` | Yes | — |

> [accordion] event full type
>
> ```ts theme={null}
> {
>   hash: string,
>   time: number,
>   type: string,
>   related_signer?: {
>     email?: string | null,
>     name?: string | null
>   } | null
> }
> ```

> [accordion] data full type
>
> ```ts theme={null}
> {
>   object: Record<string, any>
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   event: {
>     hash: string,
>     time: number,
>     type: string,
>     related_signer?: {
>       email?: string | null,
>       name?: string | null
>     } | null
>   },
>   data: {
>     object: Record<string, any>
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
signwell({
    webhookHooks: {
        document: {
            expired: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### In Progress

`document.inProgress`

The first signer started filling the document; SignWell sends this once.

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `event` | `object` | Yes | — |
| `data` | `object` | Yes | — |

> [accordion] event full type
>
> ```ts theme={null}
> {
>   hash: string,
>   time: number,
>   type: string,
>   related_signer?: {
>     email?: string | null,
>     name?: string | null
>   } | null
> }
> ```

> [accordion] data full type
>
> ```ts theme={null}
> {
>   object: Record<string, any>
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   event: {
>     hash: string,
>     time: number,
>     type: string,
>     related_signer?: {
>       email?: string | null,
>       name?: string | null
>     } | null
>   },
>   data: {
>     object: Record<string, any>
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
signwell({
    webhookHooks: {
        document: {
            inProgress: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Recipients Updated

`document.recipientsUpdated`

A sent document's recipients were changed.

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `event` | `object` | Yes | — |
| `data` | `object` | Yes | — |

> [accordion] event full type
>
> ```ts theme={null}
> {
>   hash: string,
>   time: number,
>   type: string,
>   related_signer?: {
>     email?: string | null,
>     name?: string | null
>   } | null
> }
> ```

> [accordion] data full type
>
> ```ts theme={null}
> {
>   object: Record<string, any>
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   event: {
>     hash: string,
>     time: number,
>     type: string,
>     related_signer?: {
>       email?: string | null,
>       name?: string | null
>     } | null
>   },
>   data: {
>     object: Record<string, any>
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
signwell({
    webhookHooks: {
        document: {
            recipientsUpdated: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Sent

`document.sent`

A document was sent to its recipients.

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `event` | `object` | Yes | — |
| `data` | `object` | Yes | — |

> [accordion] event full type
>
> ```ts theme={null}
> {
>   hash: string,
>   time: number,
>   type: string,
>   related_signer?: {
>     email?: string | null,
>     name?: string | null
>   } | null
> }
> ```

> [accordion] data full type
>
> ```ts theme={null}
> {
>   object: Record<string, any>
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   event: {
>     hash: string,
>     time: number,
>     type: string,
>     related_signer?: {
>       email?: string | null,
>       name?: string | null
>     } | null
>   },
>   data: {
>     object: Record<string, any>
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
signwell({
    webhookHooks: {
        document: {
            sent: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Signed

`document.signed`

One recipient signed. A document with several signers sends this once per signer.

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `event` | `object` | Yes | — |
| `data` | `object` | Yes | — |

> [accordion] event full type
>
> ```ts theme={null}
> {
>   hash: string,
>   time: number,
>   type: string,
>   related_signer?: {
>     email?: string | null,
>     name?: string | null
>   } | null
> }
> ```

> [accordion] data full type
>
> ```ts theme={null}
> {
>   object: Record<string, any>
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   event: {
>     hash: string,
>     time: number,
>     type: string,
>     related_signer?: {
>       email?: string | null,
>       name?: string | null
>     } | null
>   },
>   data: {
>     object: Record<string, any>
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
signwell({
    webhookHooks: {
        document: {
            signed: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Viewed

`document.viewed`

A signer opened the document. SignWell sends this once per view.

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `event` | `object` | Yes | — |
| `data` | `object` | Yes | — |

> [accordion] event full type
>
> ```ts theme={null}
> {
>   hash: string,
>   time: number,
>   type: string,
>   related_signer?: {
>     email?: string | null,
>     name?: string | null
>   } | null
> }
> ```

> [accordion] data full type
>
> ```ts theme={null}
> {
>   object: Record<string, any>
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   event: {
>     hash: string,
>     time: number,
>     type: string,
>     related_signer?: {
>       email?: string | null,
>       name?: string | null
>     } | null
>   },
>   data: {
>     object: Record<string, any>
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
signwell({
    webhookHooks: {
        document: {
            viewed: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***


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