PayFit Payroll Completion Health Gate

A payroll run that is still not_completed the day before payday is a problem that affects real paychecks, but PayFit's own interface has no alert for it, someone has to remember to open the company's payroll status page. This blueprint checks the status directly with io.kestra.plugin.payfit.company.GetPayrollStatus and only pages when the period is actually overdue, not every day the payroll happens to still be in progress.

This blueprint was created by Mohit Jeswani.

How it works

1. check_payroll_status (io.kestra.plugin.payfit.company.GetPayrollStatus) fetches the status (completed or not_completed) and execution end timestamp for pay_period. Read-only; nothing in PayFit is started or changed. allowFailure: true covers an API or auth error without failing the flow outright.
2. evaluate (io.kestra.plugin.core.output.OutputValues) classifies the result: completed is always OK. not_completed is only CRITICAL once today's date reaches deadline_day_of_month for pay_period's month, otherwise it is still OK, since a payroll that simply hasn't run yet this period is normal, not a problem. check_payroll_status failing outright is also CRITICAL.
3. route (io.kestra.plugin.core.flow.If):
   • compliant: logs the current status.
   • alert: posts the status and period to Slack.
4. summary logs the status and severity, closing the governance cycle.
5. errors alerts Slack if the flow itself fails, for example an expired API key.

What you get

• A Slack page only when a payroll period is genuinely overdue, not a daily reminder that it simply hasn't run yet.
• A deadline you control per company, instead of guessing when PayFit's own processing window closes.
• A read-only check with zero side effects, distinct from using a payroll-triggering task as the monitor.

Who it's for

• HR and Finance teams running payroll through PayFit who want to know a run is stuck before payday, not after an employee reports a missing paycheck.
• Teams evaluating the PayFit plugin who want a worked example of company.GetPayrollStatus used on its own as a governance check.

Why orchestrate this with Kestra

PayFit's payroll status is a page someone has to remember to open; it has no scheduled check and no alert of its own. Kestra keeps deadline_day_of_month as a flow input instead of institutional memory, turns the status into a Slack page the moment it is actually overdue, and keeps a full execution history of every check, completed or not.

Prerequisites

• A PayFit account with Partner API access and a customer API key (PayFit app, Integrations > API Access), or an OAuth access token from auth.AccessToken.
• A Slack incoming webhook URL.

This flow calls the PayFit Partner API directly over HTTPS; there is no official local PayFit emulator, so check_payroll_status cannot be exercised against a local Docker container. Use a PayFit sandbox/test company to validate this end to end.

Secrets

• PAYFIT_API_KEY: the PayFit API key or OAuth access token used by check_payroll_status. In Kestra OSS, provide it as the base64-encoded environment variable SECRET_PAYFIT_API_KEY.
• SLACK_WEBHOOK_URL: used by alert and the errors block. In Kestra OSS, provide it as the base64-encoded environment variable SECRET_SLACK_WEBHOOK_URL.

Inputs

Input	Default	Purpose
pay_period	202609	Payroll period to check, YYYYMM
company_id	empty	PayFit company ID, resolved from the API key when empty
deadline_day_of_month	25	Day of the month not_completed becomes CRITICAL

Outputs

• {{ outputs.check_payroll_status.status }}: completed or not_completed.
• {{ outputs.check_payroll_status.completed }}: boolean convenience flag.
• {{ outputs.check_payroll_status.executionEndDate }}: completion timestamp, null while not completed.
• {{ outputs.evaluate.values.severity }}: OK or CRITICAL.

Pitfalls

• deadline_day_of_month is compared against today's date within the target pay period; setting a deadline past the last calendar day of shorter months will not evaluate to CRITICAL until the next calendar month begins.
• GetPayrollStatus reports on exactly the pay_period you ask for. Checking last month's period after this month has already started tells you nothing about the current period.
• companyId left empty costs one extra PayFit token-introspection call per run; set it explicitly once you know it to skip that round trip.

Quick start

1. Add the PAYFIT_API_KEY and SLACK_WEBHOOK_URL secrets.
2. Run the flow manually with pay_period set to a period you know is already completed and confirm compliant logs it.
3. Set pay_period to the current period and deadline_day_of_month to a day already passed this month to confirm alert fires if that period is still not_completed.
4. Enable the daily trigger, which always checks the current calendar month.

How to extend

• Loop over several company_id values with io.kestra.plugin.core.flow.Loop to watch every legal entity in one scheduled run.
• Add a second, earlier warning threshold (io.kestra.plugin.core.flow.If) that logs a lower-severity reminder a few days before deadline_day_of_month, without paging Slack.
• Chain io.kestra.plugin.payfit.payslips.List after a completed result to confirm payslips were actually generated for every collaborator, not just that PayFit's own status flipped.

Links

• PayFit plugin: https://kestra.io/plugins/plugin-payfit
• PayFit Partner API: https://developers.payfit.com/
• Slack incoming webhooks: https://api.slack.com/messaging/webhooks