Manual – Private Payroll: Employment Relationships
The API is still in development phase, therefore this manual is subject to changes.
1. Document Objective
This manual describes how employment relationship monitoring works for credit borrowers in Private Payroll and how updates are notified via webhooks.
2. Context and Motivation
Private payroll credit contracts depend on active employment relationships to maintain valid reservations.
For this reason, Dataprev is consulted daily to identify changes in these relationships (e.g., termination of work contract or creation of a new relationship).
When there are changes, the system sends automatic webhooks to partners informing the new reservation status or the new detected relationship.
🔄 General Process Flow
- The system consults employment relationships daily in Dataprev.
- If an active relationship is terminated, the contract is updated and the partner is notified.
- If the worker creates a new relationship, the system automatically identifies it and tries to relink the reservation.
- Webhooks are sent at each step so the partner can keep their systems updated.
3. Webhook – Employment Relationship Termination
📅 When it is sent
When a worker loses their employment relationship and the payroll contract was associated with that relationship.
🔍 What happens
The reservation status is updated to "terminated", indicating it was closed due to relationship termination.
The partner must update their system according to this information.
💡 Payload Example
{
"status": "terminated",
"event_datetime": "2025-03-20T14:47:43Z",
"key": "<Debt Key>",
"webhook_type": "laas.private_payroll.reservation_status_change",
"data": {
"reservation_key": "<Reservation Key>",
"document_number": "12345678901",
"reservation_status": "terminated",
"requester_key": "123e4567-e89b-12d3-a456-426614174000",
"registration_number": "99999999999-A",
"employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
"admission_date": "2025-04-02",
"employer_document_number": "12345678901234",
"external_key": "123e4567-e89b-12d3-a456-426614174000",
"contract_number": "2024001234",
"inclusion_date": "2025-04-02",
"disbursement_date": "2025-04-05",
"reservation_type": "new_credit",
}
}
4. Webhook – New Employment Relationships
📅 When it is sent
When the system identifies that the worker with an active contract now has a new employment relationship, after the previous termination.
🔍 What happens
The system notifies the partner with complete data of the new relationship.
💡 Payload Example
{
"status": "active",
"event_datetime": "2025-03-20T14:47:43Z",
"key": "<Debt Key>",
"webhook_type": "laas.private_payroll.new_employment_relationship",
"data": {
"document_number": "71742311016",
"registration_number": "123456789ABCDEFR",
"employer_document_number": "02302554000179",
"status": "active",
"employment_relationship_data": {
"name": "LETYCIA AGUILAR DA SILVA",
"eligible": true,
"loan_count": 0,
"employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
"admission_date": "2025-04-02",
"total_due_amount": 1642.16,
"base_margin_amount": 911.67,
"political_exposition": "not_exposed",
"worker_category_code": 101,
"employer_document_type": "CNPJ",
"available_margin_amount": 319.08
}
}
}
5. Webhook – Reservation Relinked to New Relationship
📅 When it is sent
After the system detects a new relationship and automatically relinks a reservation that was terminated.
🔍 What happens
Relinking occurs only if the new margin is sufficient.
There is no installment recalculation or debt reprofiling.
A new reservation key (reservation_key) is generated, keeping the same credit_operation_key or external_key.
The partner receives two webhooks, one informing the new reservation with status "reserved" and another informing the status change of the old reservation to "transferred" status. This way it's possible to track relinked, terminated and transferred contracts.
💡 Payload Example - Relinked Contract
{
"status": "reserved",
"event_datetime": "2025-03-20T14:47:43Z",
"key": "<Debt Key>",
"webhook_type": "laas.private_payroll.renewed_reservation",
"data": {
"reservation_key": "<Reservation Key>",
"document_number": "12345678901",
"reservation_status": "reserved",
"requester_key": "123e4567-e89b-12d3-a456-426614174000",
"registration_number": "99999999999-A",
"employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
"admission_date": "2025-04-02",
"employer_document_number": "12345678901234",
"external_key": "123e4567-e89b-12d3-a456-426614174000",
"contract_number": "2024001234",
"inclusion_date": "2025-04-02",
"disbursement_date": "2025-04-05",
"reservation_type": "transferred",
}
}
💡 Payload Example - Transferred Contract
{
"status": "transferred",
"event_datetime": "2025-03-20T14:47:43Z",
"key": "<Debt Key>",
"webhook_type": "laas.private_payroll.reservation_status_change",
"data": {
"reservation_key": "<Reservation Key>",
"document_number": "12345678901",
"requester_key": "123e4567-e89b-12d3-a456-426614174000",
"registration_number": "99999999999-A",
"employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
"admission_date": "2025-04-02",
"employer_document_number": "12345678901234",
"external_key": "123e4567-e89b-12d3-a456-426614174000",
"contract_number": "2024001234",
"inclusion_date": "2025-04-02",
"disbursement_date": "2025-04-05",
"reservation_type": "new_credit",
"reservation_status": "transferred",
}
}
Note:
The external_key or credit_operation_key like most of the data remains the same.
6. Best Practices
Monitor your webhooks daily to ensure synchronization with the LaaS system.
Handle status updates in an idempotent way (i.e., avoid processing the same event twice).
Keep logs of webhook receipts for auditing purposes.