Kufu Smarthr Webhooks

generated: '2026-07-19'
method: searched
source: >-
  https://developer.smarthr.jp/api/about_webhook, cross-checked against the
  Webhook definition in openapi/kufu-smarthr-openapi.json
type: Webhooks
description: >-
  SmartHR's event surface. SmartHR publishes NO AsyncAPI description, so this
  is a faithful catalog of the documented webhook contract rather than a
  generated spec — nothing here is invented. Webhooks are the only push channel
  SmartHR offers; there is no streaming, SSE, or message-broker surface.

asyncapi_published: false
delivery: HTTP POST, JSON body
registration:
  ui: SmartHR admin dashboard, "External System Integration" section
  api: true
  operations:
    - getV1Webhooks
    - postV1Webhooks
    - getV1WebhooksId
    - putV1WebhooksId
    - patchV1WebhooksId
    - deleteV1WebhooksId
  fields:
    url: Destination endpoint receiving the POST. Required.
    event: >-
      Which events to subscribe to. On the API resource these are individual
      boolean flags (crew_created, crew_updated, ...), each defaulting to
      required.
    secret_token: >-
      Optional shared secret, echoed back on delivery in the X-SmartHR-Token
      request header.
    description: Optional free-text note.
    expose_only_id: >-
      When true, deliver only the id of the changed record instead of the full
      object.
    access_type:
      enum: [read_and_update, hidden, read_and_update_only_origin]

security:
  mechanism: shared secret in a request header
  header: X-SmartHR-Token
  signature_verification: false
  note: >-
    SmartHR echoes the configured secret token verbatim in X-SmartHR-Token. It
    does NOT compute an HMAC signature over the payload, so a consumer can only
    verify the sender knows the secret — it cannot verify payload integrity or
    replay-protect a delivery. Consumers should terminate TLS themselves,
    compare the token in constant time, and treat the payload as untrusted
    until re-read from the API.

envelope:
  fields:
    event:
      type: string
      description: The event id (see events[] below).
    triggered_at:
      type: string
      format: ISO 8601
      description: When the event fired.
    sender:
      type: object
      nullable: true
      description: The Crew object that caused the change, or null.
    payload:
      description: >-
        One event-specific key carrying the subject — one of crew,
        crew_import_result, dependent, dependent_import_result, or workflow.

events:
  - id: crew_created
    trigger: Employee record created.
    payload_key: crew
    payload_object: Crew
  - id: crew_updated
    trigger: Employee record modified.
    payload_key: crew
    payload_object: Crew
    note: >-
      For future-effective changes this fires on the effective date, not when
      the change was booked.
  - id: crew_deleted
    trigger: Employee record fully removed.
    payload_key: crew
    payload_object: Crew
  - id: crew_imported
    trigger: Batch employee import completed.
    payload_key: crew_import_result
    payload_object: CrewImportResult
  - id: dependent_created
    trigger: Family/dependent record created.
    payload_key: dependent
    payload_object: Dependent
  - id: dependent_updated
    trigger: Family/dependent record modified.
    payload_key: dependent
    payload_object: Dependent
  - id: dependent_deleted
    trigger: Family/dependent record removed.
    payload_key: dependent
    payload_object: Dependent
  - id: dependent_imported
    trigger: Batch family import completed.
    payload_key: dependent_import_result
    payload_object: DependentImportResult
  - id: workflow_approved
    trigger: A workflow reached its final approval step.
    payload_key: workflow
    payload_object: Workflow
    note: Fires immediately on approval, regardless of effective dating.

delivery_semantics:
  success_criteria: A 2xx HTTP response returned within 60 seconds.
  timeout_seconds: 60
  retries:
    production:
      attempts: ~17
      window: ~3 days
    sandbox:
      attempts: ~5
      window: ~8 minutes
  on_exhaustion: The webhook registration is disabled.
  ordering: not guaranteed / not documented
  deduplication: not documented

suppression:
  parameter: skip_sending_webhook=true
  description: >-
    Append to an API write request to suppress webhook delivery for that
    operation. The standard guard against infinite loops when a webhook
    consumer writes back into SmartHR.

payload_state_semantics: >-
  Payloads always reflect the employee's state at send time, even when the
  underlying change carries a future effective date. Consumers that need the
  booked-versus-effective distinction must re-read the record through the API.

related:
  conventions: conventions/kufu-conventions.yml
  openapi: openapi/kufu-smarthr-openapi.json
  docs: https://developer.smarthr.jp/api/about_webhook