openapi: 3.0.3
info:
  title: Hubstaff Activities Webhooks API
  description: 'The Hubstaff API v2 provides programmatic read and write access to Hubstaff''s time tracking, timesheet, workforce management, and project management data - organizations, members, teams, projects, tasks, clients, activities (10-minute tracked time blocks with activity percentages), daily activity aggregates, time entries, timesheets and approvals, time off requests/policies/balances, attendance schedules and shifts, screenshots, app and URL usage, invoices, team payments, and webhooks.


    Authentication uses OpenID Connect / OAuth 2.0 through Hubstaff Account (https://account.hubstaff.com). For server-side scripts, create a personal access token at https://developer.hubstaff.com/personal_access_tokens - the PAT acts as an OAuth refresh token (90-day expiry) that you exchange for short-lived access tokens at https://account.hubstaff.com/access_tokens. Send the access token as a Bearer token on every request.


    Rate limit: authenticated users are allowed 1,000 requests per hour per application; individual requests time out after 30 seconds. All requests must use HTTPS. Collection endpoints use cursor pagination via page_start_id and page_limit. This document is a curated OpenAPI 3.0 rendering of the live Swagger 2.0 definition published at https://api.hubstaff.com/v2/docs, covering the primary resource areas; consult the live definition for the complete surface (insights, job sites, budgets, overtime policies, integrations, and more).'
  version: '2.0'
  contact:
    name: Hubstaff Developer Portal
    url: https://developer.hubstaff.com/
  termsOfService: https://hubstaff.com/terms
servers:
- url: https://api.hubstaff.com
  description: Hubstaff production API (paths include the /v2 prefix)
security:
- oauth2:
  - hubstaff:read
- personalAccessToken: []
tags:
- name: Webhooks
  description: Webhook subscriptions delivering real-time event notifications (timer.start, timer.stop, task.create, shift.late, etc.).
paths:
  /v2/organizations/{organization_id}/webhooks:
    post:
      operationId: postV2OrganizationsOrganizationIdWebhooks
      tags:
      - Webhooks
      summary: Create organization webhook
      description: 'Creates a new webhook subscription for the organization. After creation, Hubstaff will send a POST request to your `target_url` with an empty body and an `X-Hook-Secret` header.


        Your endpoint must respond with HTTP 200 and echo the same `X-Hook-Secret` header to verify ownership.


        Store the secret value - you''ll need it to activate the webhook.'
      parameters:
      - name: organization_id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request payload. See the live Hubstaff API reference (https://api.hubstaff.com/v2/docs) for the full schema.
      responses:
        '201':
          description: Create organization webhook
        '429':
          description: Rate limit exceeded (1,000 requests per hour per application).
  /v2/webhooks/{webhook_id}:
    get:
      operationId: getV2WebhooksWebhookId
      tags:
      - Webhooks
      summary: Get webhook
      description: Returns the details of a specific webhook including its status, events, and target URL.
      parameters:
      - name: webhook_id
        in: path
        description: Webhook ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Get webhook
        '429':
          description: Rate limit exceeded (1,000 requests per hour per application).
    delete:
      operationId: deleteV2WebhooksWebhookId
      tags:
      - Webhooks
      summary: Delete webhook
      description: Permanently deletes a webhook. The webhook will stop receiving events immediately.
      parameters:
      - name: webhook_id
        in: path
        description: Webhook ID
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Delete webhook
        '429':
          description: Rate limit exceeded (1,000 requests per hour per application).
  /v2/webhooks/{webhook_id}/activate:
    post:
      operationId: postV2WebhooksWebhookIdActivate
      tags:
      - Webhooks
      summary: Activate webhook
      description: 'Activates a webhook after endpoint verification.


        You must include the `X-Hook-Secret` header with the secret value you received during the verification step.


        Once activated, the webhook will start receiving events.'
      parameters:
      - name: webhook_id
        in: path
        description: Webhook ID
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Activate webhook
        '429':
          description: Rate limit exceeded (1,000 requests per hour per application).
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: Hubstaff Account OpenID Connect / OAuth 2.0 authentication. Scopes are hubstaff:read and hubstaff:write.
      flows:
        authorizationCode:
          authorizationUrl: https://account.hubstaff.com/authorizations/new
          tokenUrl: https://account.hubstaff.com/access_tokens
          scopes:
            hubstaff:read: Read access to the Hubstaff API
            hubstaff:write: Write access to the Hubstaff API
    personalAccessToken:
      type: http
      scheme: bearer
      description: Access token obtained by exchanging a personal access token (created at https://developer.hubstaff.com/personal_access_tokens) via the OAuth 2.0 refresh token grant at https://account.hubstaff.com/access_tokens. PATs expire after 90 days.
externalDocs:
  description: Hubstaff API v2 reference (interactive)
  url: https://developer.hubstaff.com/docs/hubstaff_v2