> For the complete documentation index, see [llms.txt](https://docs.shortcutco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shortcutco.com/developers/api-reference/reference/objects/webhook.md).

# The webhook object

The webhook object in the Shortcut API - every field, an example, and the endpoints that return it.

A webhook subscription: where to send which events.

## Fields

| Field                     | Type                                                   | Description                                                                                                                                                                                                                                                        |
| ------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`                      | id                                                     | The subscription's id.                                                                                                                                                                                                                                             |
| `object`                  | `"webhook"`                                            | Always `webhook`.                                                                                                                                                                                                                                                  |
| `url`                     | string                                                 | The HTTPS endpoint (port 443) events are sent to.                                                                                                                                                                                                                  |
| `description`             | string or null                                         | A note to tell subscriptions apart.                                                                                                                                                                                                                                |
| `eventTypes`              | array of [event types](/developers/webhooks/events.md) | The event types this subscription receives.                                                                                                                                                                                                                        |
| `requiredScopes`          | array of string                                        | The read scopes of the subscribed event families, fixed when the subscription was created or its events last changed. Payloads are serialized under exactly these scopes.                                                                                          |
| `status`                  | `active`, `paused`, `disabled`                         | `active` subscriptions receive events. `paused` ones hold their events until resumed. `disabled` ones were turned off after 50 failed deliveries in a row; events that happen while disabled are not kept.                                                         |
| `consecutiveFailures`     | integer                                                | Failed delivery attempts in a row; a success resets it.                                                                                                                                                                                                            |
| `disabledAt`              | timestamp or null                                      | When delivery turned the subscription off, ISO 8601 in UTC.                                                                                                                                                                                                        |
| `previousSecretExpiresAt` | timestamp or null                                      | Until when the secret replaced by the last rotation still signs deliveries (24 hours after rotating), ISO 8601 in UTC.                                                                                                                                             |
| `createdVia`              | `settings`, `api_token`                                | Whether an admin created it in Settings or an integration created it with a token.                                                                                                                                                                                 |
| `createdAt`               | timestamp                                              | When the subscription was created, ISO 8601 in UTC.                                                                                                                                                                                                                |
| `updatedAt`               | timestamp                                              | When the subscription last changed, ISO 8601 in UTC.                                                                                                                                                                                                               |
| `secret`                  | string                                                 | The signing secret (`whsec_…`), returned only in this response. It is not stored for idempotent replays: a replay omits it, so rotate the secret if you lost the first response. Only in answers from `POST /v1/webhooks`, `POST /v1/webhooks/{id}/rotate-secret`. |

## Example

```json
{
  "id": "8e165c48-8a60-478f-86aa-d2d682f50e1d",
  "object": "webhook",
  "url": "https://example.com/shortcut/webhooks",
  "description": null,
  "eventTypes": [
    "customer.created"
  ],
  "requiredScopes": [
    "customers:read"
  ],
  "status": "active",
  "consecutiveFailures": 0,
  "disabledAt": null,
  "previousSecretExpiresAt": null,
  "createdVia": "api_token",
  "createdAt": "2026-10-16T17:04:12.381Z",
  "updatedAt": "2026-10-16T17:04:12.381Z",
  "secret": "whsec_…"
}
```

## Endpoints

| Endpoint                               | What it does                      |
| -------------------------------------- | --------------------------------- |
| `GET /v1/webhooks`                     | List webhooks                     |
| `POST /v1/webhooks`                    | Create a webhook                  |
| `GET /v1/webhooks/{id}`                | Get a webhook                     |
| `PATCH /v1/webhooks/{id}`              | Update a webhook                  |
| `DELETE /v1/webhooks/{id}`             | Delete a webhook                  |
| `POST /v1/webhooks/{id}/rotate-secret` | Rotate a webhook's signing secret |