List webhooks

This API method returns the webhooks the key owner can see. Requires webhooks:read. Admins see every webhook in the company; other users see only the webhooks they own. Webhooks follow the key owner, not the key, so X-On-Behalf-Of is ignored.

The list is paginated: 25 webhooks per page by default, up to 100 with limit. When nextToken is present, pass it back to get the next page. The signing secret is never returned here; secretPrefix helps you tell secrets apart.

Errors: 400 when limit or nextToken is invalid (see BadRequest), and 403 FORBIDDEN (the key owner no longer exists).

Authorization

bearerAuth webhooks:read

AuthorizationBearer <token>

API key sent as Authorization: Bearer vt_live_<secret>. See the Authentication and Scopes sections at the top of this document for how keys are created, which scopes exist and how the key owner's role limits them.

In: header

Scope: webhooks:read

Query Parameters

limit?integer

the number of webhooks to return per page, between 1 and 100, default is 25. A page can hold fewer webhooks even when more exist; rely on nextToken.

Default25

Range1 <= value <= 100

nextToken?string

The nextToken returned by the previous API call. Send the same filters as in the previous call. Same semantics as the v1 nextToken parameter; a token that was not issued by this API fails with 400 INVALID_PAGINATION_TOKEN.

Response Body

`application/json`

curl -X GET "https://example.com/v2/webhooks"

{
  "data": [
    {
      "webhookId": "wh_3f1c2b9e-8a47-4d5e-9c61-2b7f0e4a1d93",
      "url": "https://example.com/vacation-tracker/webhooks",
      "description": "Sync leaves to payroll",
      "events": [
        "leave.approved",
        "leave.cancelled"
      ],
      "status": "active",
      "pausedReason": null,
      "pausedAt": null,
      "revokedAt": null,
      "revocationReason": null,
      "ownerId": "user-63b17e97-d38b-4586-8498-bb4f5d2e2c14",
      "secretPrefix": "whsec_AbCd",
      "lastDelivery": {
        "deliveryId": "dlv_1790157600000_8a47c61e2b7f4d5e9c613f1c2b9e1d93",
        "eventName": "leave.approved",
        "status": "SUCCEEDED",
        "responseStatus": 200,
        "at": "2026-09-23T10:00:00.000Z"
      },
      "createdAt": "2026-09-01T08:00:00.000Z",
      "updatedAt": "2026-09-23T10:00:00.000Z"
    },
    {
      "webhookId": "wh_9c612b7f-0e4a-4d93-8a47-3f1c2b9e4d5e",
      "url": "https://example.com/vacation-tracker/operations",
      "description": null,
      "events": [
        "operation.completed",
        "operation.failed"
      ],
      "status": "paused",
      "pausedReason": "endpoint-gone",
      "pausedAt": "2026-09-20T12:00:00.000Z",
      "revokedAt": null,
      "revocationReason": null,
      "ownerId": "user-63b17e97-d38b-4586-8498-bb4f5d2e2c14",
      "secretPrefix": "whsec_Zy98",
      "lastDelivery": {
        "deliveryId": "dlv_1789905600000_2b7f0e4a1d934c618a473f1c2b9e4d5e",
        "eventName": "operation.completed",
        "status": "FAILED",
        "responseStatus": 410,
        "at": "2026-09-20T12:00:00.000Z"
      },
      "createdAt": "2026-08-15T09:00:00.000Z",
      "updatedAt": "2026-09-20T12:00:00.000Z"
    }
  ],
  "nextToken": "eyJjb21wYW55SWQiOiJjNmFmOWFjNiJ9"
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "name": "ValidationError",
    "description": "A query parameter, body field or header failed validation.",
    "resolution": "Fix the fields listed in details.fields and send the request again.",
    "requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef",
    "details": {
      "fields": [
        {
          "path": "startDate",
          "message": "\"startDate\" is required"
        }
      ]
    }
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "name": "Unauthorized",
    "description": "The API key is missing, malformed or not recognized.",
    "resolution": "Send a valid API key in the Authorization header as Bearer followed by the full vt_live_ key.",
    "requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef"
  }
}

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "name": "InsufficientScope",
    "description": "The API key does not have the scopes this request needs.",
    "resolution": "Add the scopes listed in details.requiredScopes to the key in the Vacation Tracker dashboard.",
    "requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef",
    "details": {
      "requiredScopes": [
        "leaves:write"
      ]
    }
  }
}

{
  "error": {
    "code": "RATE_LIMITED",
    "name": "RateLimited",
    "description": "Too many requests were sent in a short time.",
    "resolution": "Wait a few seconds and retry, using the same Idempotency-Key for writes.",
    "requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef"
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "name": "InternalError",
    "description": "Something went wrong on our side.",
    "resolution": "Retry later, and if it keeps happening, contact Vacation Tracker support and quote the requestId.",
    "requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef"
  }
}

Authorization

Query Parameters

Response Body

200application/json

400application/json

401application/json

403application/json

429application/json

500application/json

Key lacks a required scope

Key was revoked

Acting user may not perform the action

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`