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

# Timely webhooks

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

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

* `projects`
  * `created` (`projects.created`)
  * `deleted` (`projects.deleted`)
  * `updated` (`projects.updated`)
* `tags`
  * `created` (`tags.created`)
  * `deleted` (`tags.deleted`)
  * `updated` (`tags.updated`)
* `tasks`
  * `created` (`tasks.created`)
  * `deleted` (`tasks.deleted`)
  * `updated` (`tasks.updated`)
* `timeEntries`
  * `created` (`timeEntries.created`)
  * `deleted` (`timeEntries.deleted`)
  * `updated` (`timeEntries.updated`)

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

## Projects

### Created

`projects.created`

A project was created

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `event` | `string` | Yes | — |
| `payload` | `object` | Yes | — |

> [accordion] payload full type
>
> ```ts theme={null}
> {
>   entity_id: number | string,
>   entity_type: string,
>   entity_path?: string | null,
>   entity_external_id?: string | null,
>   updated_from?: string | null,
>   updated_at?: string | null,
>   status?: string | null,
>   date?: string | null
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   event: string,
>   payload: {
>     entity_id: number | string,
>     entity_type: string,
>     entity_path?: string | null,
>     entity_external_id?: string | null,
>     updated_from?: string | null,
>     updated_at?: string | null,
>     status?: string | null,
>     date?: string | null
>   }
> }
> ```

**`webhookHooks` example**

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

***

### Deleted

`projects.deleted`

A project was deleted

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `event` | `string` | Yes | — |
| `payload` | `object` | Yes | — |

> [accordion] payload full type
>
> ```ts theme={null}
> {
>   entity_id: number | string,
>   entity_type: string,
>   entity_path?: string | null,
>   entity_external_id?: string | null,
>   updated_from?: string | null,
>   updated_at?: string | null,
>   status?: string | null,
>   date?: string | null
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   event: string,
>   payload: {
>     entity_id: number | string,
>     entity_type: string,
>     entity_path?: string | null,
>     entity_external_id?: string | null,
>     updated_from?: string | null,
>     updated_at?: string | null,
>     status?: string | null,
>     date?: string | null
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
timely({
    webhookHooks: {
        projects: {
            deleted: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Updated

`projects.updated`

A project changed

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `event` | `string` | Yes | — |
| `payload` | `object` | Yes | — |

> [accordion] payload full type
>
> ```ts theme={null}
> {
>   entity_id: number | string,
>   entity_type: string,
>   entity_path?: string | null,
>   entity_external_id?: string | null,
>   updated_from?: string | null,
>   updated_at?: string | null,
>   status?: string | null,
>   date?: string | null
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   event: string,
>   payload: {
>     entity_id: number | string,
>     entity_type: string,
>     entity_path?: string | null,
>     entity_external_id?: string | null,
>     updated_from?: string | null,
>     updated_at?: string | null,
>     status?: string | null,
>     date?: string | null
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
timely({
    webhookHooks: {
        projects: {
            updated: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

## Tags

### Created

`tags.created`

A tag was created (Timely event labels:created)

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `event` | `string` | Yes | — |
| `payload` | `object` | Yes | — |

> [accordion] payload full type
>
> ```ts theme={null}
> {
>   entity_id: number | string,
>   entity_type: string,
>   entity_path?: string | null,
>   entity_external_id?: string | null,
>   updated_from?: string | null,
>   updated_at?: string | null,
>   status?: string | null,
>   date?: string | null
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   event: string,
>   payload: {
>     entity_id: number | string,
>     entity_type: string,
>     entity_path?: string | null,
>     entity_external_id?: string | null,
>     updated_from?: string | null,
>     updated_at?: string | null,
>     status?: string | null,
>     date?: string | null
>   }
> }
> ```

**`webhookHooks` example**

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

***

### Deleted

`tags.deleted`

A tag was deleted (Timely event labels:deleted)

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `event` | `string` | Yes | — |
| `payload` | `object` | Yes | — |

> [accordion] payload full type
>
> ```ts theme={null}
> {
>   entity_id: number | string,
>   entity_type: string,
>   entity_path?: string | null,
>   entity_external_id?: string | null,
>   updated_from?: string | null,
>   updated_at?: string | null,
>   status?: string | null,
>   date?: string | null
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   event: string,
>   payload: {
>     entity_id: number | string,
>     entity_type: string,
>     entity_path?: string | null,
>     entity_external_id?: string | null,
>     updated_from?: string | null,
>     updated_at?: string | null,
>     status?: string | null,
>     date?: string | null
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
timely({
    webhookHooks: {
        tags: {
            deleted: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Updated

`tags.updated`

A tag changed (Timely event labels:updated)

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `event` | `string` | Yes | — |
| `payload` | `object` | Yes | — |

> [accordion] payload full type
>
> ```ts theme={null}
> {
>   entity_id: number | string,
>   entity_type: string,
>   entity_path?: string | null,
>   entity_external_id?: string | null,
>   updated_from?: string | null,
>   updated_at?: string | null,
>   status?: string | null,
>   date?: string | null
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   event: string,
>   payload: {
>     entity_id: number | string,
>     entity_type: string,
>     entity_path?: string | null,
>     entity_external_id?: string | null,
>     updated_from?: string | null,
>     updated_at?: string | null,
>     status?: string | null,
>     date?: string | null
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
timely({
    webhookHooks: {
        tags: {
            updated: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

## Tasks

### Created

`tasks.created`

A task was created (Timely event forecasts:created)

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `event` | `string` | Yes | — |
| `payload` | `object` | Yes | — |

> [accordion] payload full type
>
> ```ts theme={null}
> {
>   entity_id: number | string,
>   entity_type: string,
>   entity_path?: string | null,
>   entity_external_id?: string | null,
>   updated_from?: string | null,
>   updated_at?: string | null,
>   status?: string | null,
>   date?: string | null
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   event: string,
>   payload: {
>     entity_id: number | string,
>     entity_type: string,
>     entity_path?: string | null,
>     entity_external_id?: string | null,
>     updated_from?: string | null,
>     updated_at?: string | null,
>     status?: string | null,
>     date?: string | null
>   }
> }
> ```

**`webhookHooks` example**

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

***

### Deleted

`tasks.deleted`

A task was deleted (Timely event forecasts:deleted)

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `event` | `string` | Yes | — |
| `payload` | `object` | Yes | — |

> [accordion] payload full type
>
> ```ts theme={null}
> {
>   entity_id: number | string,
>   entity_type: string,
>   entity_path?: string | null,
>   entity_external_id?: string | null,
>   updated_from?: string | null,
>   updated_at?: string | null,
>   status?: string | null,
>   date?: string | null
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   event: string,
>   payload: {
>     entity_id: number | string,
>     entity_type: string,
>     entity_path?: string | null,
>     entity_external_id?: string | null,
>     updated_from?: string | null,
>     updated_at?: string | null,
>     status?: string | null,
>     date?: string | null
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
timely({
    webhookHooks: {
        tasks: {
            deleted: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Updated

`tasks.updated`

A task changed (Timely event forecasts:updated)

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `event` | `string` | Yes | — |
| `payload` | `object` | Yes | — |

> [accordion] payload full type
>
> ```ts theme={null}
> {
>   entity_id: number | string,
>   entity_type: string,
>   entity_path?: string | null,
>   entity_external_id?: string | null,
>   updated_from?: string | null,
>   updated_at?: string | null,
>   status?: string | null,
>   date?: string | null
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   event: string,
>   payload: {
>     entity_id: number | string,
>     entity_type: string,
>     entity_path?: string | null,
>     entity_external_id?: string | null,
>     updated_from?: string | null,
>     updated_at?: string | null,
>     status?: string | null,
>     date?: string | null
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
timely({
    webhookHooks: {
        tasks: {
            updated: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

## Time Entries

### Created

`timeEntries.created`

A time entry was logged (Timely event hours:created)

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `event` | `string` | Yes | — |
| `payload` | `object` | Yes | — |

> [accordion] payload full type
>
> ```ts theme={null}
> {
>   entity_id: number | string,
>   entity_type: string,
>   entity_path?: string | null,
>   entity_external_id?: string | null,
>   updated_from?: string | null,
>   updated_at?: string | null,
>   status?: string | null,
>   date?: string | null
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   event: string,
>   payload: {
>     entity_id: number | string,
>     entity_type: string,
>     entity_path?: string | null,
>     entity_external_id?: string | null,
>     updated_from?: string | null,
>     updated_at?: string | null,
>     status?: string | null,
>     date?: string | null
>   }
> }
> ```

**`webhookHooks` example**

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

***

### Deleted

`timeEntries.deleted`

A time entry was deleted (Timely event hours:deleted)

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `event` | `string` | Yes | — |
| `payload` | `object` | Yes | — |

> [accordion] payload full type
>
> ```ts theme={null}
> {
>   entity_id: number | string,
>   entity_type: string,
>   entity_path?: string | null,
>   entity_external_id?: string | null,
>   updated_from?: string | null,
>   updated_at?: string | null,
>   status?: string | null,
>   date?: string | null
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   event: string,
>   payload: {
>     entity_id: number | string,
>     entity_type: string,
>     entity_path?: string | null,
>     entity_external_id?: string | null,
>     updated_from?: string | null,
>     updated_at?: string | null,
>     status?: string | null,
>     date?: string | null
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
timely({
    webhookHooks: {
        timeEntries: {
            deleted: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Updated

`timeEntries.updated`

A time entry changed (Timely event hours:updated)

**Payload**

| Name | Type | Required | Description |
| - | - | - | - |
| `event` | `string` | Yes | — |
| `payload` | `object` | Yes | — |

> [accordion] payload full type
>
> ```ts theme={null}
> {
>   entity_id: number | string,
>   entity_type: string,
>   entity_path?: string | null,
>   entity_external_id?: string | null,
>   updated_from?: string | null,
>   updated_at?: string | null,
>   status?: string | null,
>   date?: string | null
> }
> ```

> [accordion] Response data full type
>
> ```ts theme={null}
> {
>   event: string,
>   payload: {
>     entity_id: number | string,
>     entity_type: string,
>     entity_path?: string | null,
>     entity_external_id?: string | null,
>     updated_from?: string | null,
>     updated_at?: string | null,
>     status?: string | null,
>     date?: string | null
>   }
> }
> ```

**`webhookHooks` example**

```ts theme={null}
timely({
    webhookHooks: {
        timeEntries: {
            updated: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***


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