Vacation TrackerDeveloper Docs
REST API v2API referenceWebhooks

Create a webhook

This API method creates a webhook owned by the key owner and returns it with 201 and its signing secret (whsec_...). Requires webhooks:write. **The secret is shown only in this response**; store it securely, and use POST /v2/webhooks/{id}/rotate-secret if you lose it. The webhook is created active.

  • url must be an absolute HTTPS URL on a publicly reachable host; other URLs fail with 400 WEBHOOK_URL_INVALID.
  • events lists the event types to receive (see WebhookEventType and the webhooks section); an empty list or an unknown type fails with 400 WEBHOOK_EVENTS_INVALID, and webhook.test cannot be subscribed to. Each event's capability must be within the owner's role and the key's scopes, otherwise the request fails with 403 WEBHOOK_EVENTS_NOT_ALLOWED.
  • description is optional, up to 200 characters.

A webhook.test delivery is sent to the new webhook right away. The Idempotency-Key and X-On-Behalf-Of headers are ignored.

Errors: 400 VALIDATION_ERROR (details.fields, for example a missing url or events, a description over 200 characters, or an unknown field), 400 INVALID_REQUEST_BODY, 400 WEBHOOK_URL_INVALID, 400 WEBHOOK_EVENTS_INVALID, 403 WEBHOOK_EVENTS_NOT_ALLOWED, and 403 FORBIDDEN (the key owner no longer exists).

POST
/v2/webhooks

Authorization

bearerAuth webhooks:write
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:write

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v2/webhooks" \  -H "Content-Type: application/json" \  -d '{    "url": "https://example.com/vacation-tracker/webhooks",    "events": [      "leave.approved",      "leave.cancelled"    ],    "description": "Sync leaves to payroll"  }'
{
  "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",
    "secret": "whsec_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789-_AbCd",
    "lastDelivery": null,
    "createdAt": "2026-09-01T08:00:00.000Z",
    "updatedAt": "2026-09-01T08:00:00.000Z"
  }
}
{
  "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"
  }
}

Need help?

developers@vacationtracker.io

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.

Get a webhook

This API method returns a single webhook, including its last delivery. Requires webhooks:read. The signing secret is never returned here.