> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Personio Webhook Setup Guide

> Configure Personio to deliver events to StackOne.

## Prerequisites

The connector should already be set up, with a Connector Profile and a Linked Account. See [Getting Started](/connectors/personio#getting-started) on the Personio connector page.

<section data-guide-section data-guide-scopes="">
  <h2>Automatic webhook setup</h2>

  <p>StackOne creates and manages the Personio webhook subscription automatically when the account is connected, and removes it when the account is disconnected. There is nothing to configure in Personio beyond the access right below.</p>

  <Steps>
    <Step title="Grant Webhooks access">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>When creating the custom integration in Personio, grant the Webhooks access right.</p>

        <ul>
          <li>Go to <strong>Settings</strong> > <strong>Integrations</strong> > <strong>API credentials</strong></li>
          <li>In the custom integration's access rights, select <strong>Read</strong> and <strong>Write</strong> for <strong>Webhooks</strong></li>
          <li>Personio allows up to 50 webhooks per company, so remove unused webhooks if the limit is reached</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Available webhook events</h2>

  <p>The following Personio events can be enabled. Only events selected in StackOne are included in the subscription, so Personio will not deliver events that are not subscribed.</p>

  <Steps>
    <Step title="Person events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to people (employee profiles).</p>

        <ul>
          <li><strong>Person Created</strong> (`person.created`) — Fired when a new person is created</li>
          <li><strong>Person Updated</strong> (`person.updated`) — Fired when a person profile is updated</li>
          <li><strong>Person Deleted</strong> (`person.deleted`) — Fired when a person is deleted</li>
        </ul>
      </div>
    </Step>

    <Step title="Employment events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to a person's employments.</p>

        <ul>
          <li><strong>Employment Created</strong> (`employment.created`) — Fired when a new employment is created for a person</li>
          <li><strong>Employment Updated</strong> (`employment.updated`) — Fired when an employment is updated</li>
          <li><strong>Employment Cost Centers Updated</strong> (`employment.updated.cost-centers`) — Fired when the cost centers of an employment change</li>
          <li><strong>Employment Deleted</strong> (`employment.deleted`) — Fired when an employment is deleted</li>
          <li><strong>Employment Started</strong> (`employment.started`) — Fired when an employment reaches its start date</li>
          <li><strong>Employment Terminated</strong> (`employment.terminated`) — Fired when an employment is terminated</li>
        </ul>
      </div>
    </Step>

    <Step title="Absence events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to absence periods (time off).</p>

        <ul>
          <li><strong>Absence Period Created</strong> (`absence-period.created`) — Fired when a new absence period is requested or created</li>
          <li><strong>Absence Period Status Updated</strong> (`absence-period.updated.status`) — Fired when the approval status of an absence period changes</li>
          <li><strong>Absence Period Timerange Updated</strong> (`absence-period.updated.timerange`) — Fired when the start or end of an absence period changes</li>
          <li><strong>Absence Period Deleted</strong> (`absence-period.deleted`) — Fired when an absence period is deleted</li>
        </ul>
      </div>
    </Step>

    <Step title="Attendance events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to attendance periods (worked time).</p>

        <ul>
          <li><strong>Attendance Period Created</strong> (`attendance-period.created`) — Fired when a new attendance period is recorded</li>
          <li><strong>Attendance Period Updated</strong> (`attendance-period.updated`) — Fired when an attendance period is updated</li>
          <li><strong>Attendance Period Deleted</strong> (`attendance-period.deleted`) — Fired when an attendance period is deleted</li>
        </ul>
      </div>
    </Step>

    <Step title="Document events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to employee documents.</p>

        <ul>
          <li><strong>Document Created</strong> (`document.created`) — Fired when a new document is uploaded</li>
          <li><strong>Document Updated</strong> (`document.updated`) — Fired when a document is updated</li>
          <li><strong>Document Deleted</strong> (`document.deleted`) — Fired when a document is deleted</li>
          <li><strong>Document Signed</strong> (`document.signed`) — Fired when a document is signed</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Delivery format</h2>

  <p>Details of how Personio delivers events to StackOne.</p>

  <Steps>
    <Step title="Identifier-only payloads">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Each request carries a single event with `company_id`, `event_name`, `occurred_at` and a `payload` holding only the identifiers of the affected records (for example `payload.person.id`). Use the matching get action to fetch the full record. Personio retries failed deliveries for up to 3 days, so the same event can arrive more than once.</p>
      </div>
    </Step>
  </Steps>
</section>

## Verify

Your Connector should now be able to receive and process events. Try triggering an event and you should see an Event appear in the Connector logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.