Signing HR contracts inside your HR software

Offer letters, employment contracts, amendments: how to embed PDF signing in your HRIS, with signer order, webhooks and HR data kept under control.

Published Oct 3, 2026 · 7 min read

To get HR contracts signed inside your HR software, trigger a signature request from an HRIS event (candidate hired, amendment approved, new policy published), send the PDF and the signers in the order you need, then file the signed PDF in the employee record when the webhook arrives. Employees sign without leaving your product or creating an account elsewhere, and HR teams follow progress from the screens they already use.

This guide is for vendors of HRIS, payroll and workforce software and their product teams. It covers the HR document lifecycle, how it maps to API calls, how to handle personal data, and the legal checks to run with your customers.

The HR documents to sign

An HRIS produces documents at every stage of an employee’s life. They do not all need the same flow: an offer letter should be signed quickly, an employment contract involves several people, and a policy acknowledgement may go to hundreds of employees at once.

Start with the two or three documents that matter most to your customers’ daily work. In most HR products these are contracts and amendments, because a pending contract blocks a start date or a payroll run.

Who signs, and in which order

In the API, each signer has a stable `reference` (for example employee, manager, hr_director) and an `order`. The signer with order 1 receives the document first, order 2 next, and so on. A request accepts up to 10 signers and 100 fields, which covers common HR flows with room to spare.

1. The employee or candidate signs first, confirming the terms that apply to them.
2. The line manager approves next, if your customer requires it for that document type.
3. The HR director or legal representative signs last on behalf of the employer.

Some companies prefer the reverse, with the employer signing first. Make the order configurable per document type in your product instead of hard-coding it. If someone declines, the `signature_request.declined` event lets you move the file back to the previous step.

Templates and field detection

A customer’s contracts usually share one layout. Prepare a template once in the Khatm platform, with roles and field positions, then reuse it by passing its `template_id` when creating a request. `GET /v1/templates` lists the available templates. Signer references must match the template roles.

For documents whose layout varies, such as an amendment drafted by a lawyer, create the request without fields, call `POST /signature-requests/{id}/detect-fields`, let the HR user review the suggestions, then confirm them with `PUT /signature-requests/{id}/fields`. Detection proposes positions; your interface gets them approved.

Connecting HRIS events to the API

The simplest integration starts from events your HRIS already knows about. Each event maps to one or two calls.

Build the `client_reference` from your own identifiers, for example employee ID, document type and version. Request creation is idempotent on that value: if a job is replayed or a user clicks twice, no duplicate request is created.

curl -sS https://<khatm-host>/v1/signature-requests \
  -H "Authorization: Bearer $KHATM_API_KEY" \
  -F "document=@contrat-cdi-0042.pdf;type=application/pdf" \
  -F 'request={
    "client_reference": "hris-contract-emp-0042-v1",
    "template_id": "<template-id>",
    "signers": [
      {"reference": "employee", "name": "Salma B.", "email": "salma@example.com", "order": 1},
      {"reference": "manager", "name": "Karim A.", "email": "karim@example.com", "order": 2},
      {"reference": "hr_director", "name": "Nadia R.", "email": "nadia@example.com", "order": 3}
    ],
    "callback_url": "https://hris.example.com/webhooks/khatm"
  }'

Creating a signature request for a contract, three signers in order (sandbox)

Updating the employee record

When the last signer has signed, Khatm sends `signature_request.completed` to your `callback_url`. The webhook is signed with HMAC-SHA256 using your `whsec_…` secret (`webhook-signature` header) and carries the `client_reference`, so you can find the employee without an extra mapping table.

{
  "id": "evt_…",
  "type": "signature_request.completed",
  "data": {
    "signature_request_id": "<request-id>",
    "client_reference": "hris-contract-emp-0042-v1",
    "status": "completed"
  },
  "created_at": "2026-10-03T09:12:00Z"
}

Useful fields of a completion event (simplified)

• Verify the webhook signature on the raw body and ignore events you have already processed.
• Download the signed PDF, the PDF evidence report and the JSON evidence, then file them in the employee record.
• Mark the contract as signed and unlock the next steps, such as account creation and payroll setup.
• Handle `signature_request.declined` and `signature_request.cancelled` too, so a record is never left in an unclear state.

Protecting HR data

An employment contract holds a salary, an address and sometimes an ID number. Send Khatm only what signing needs: the PDF and each signer’s name and email. The rest of the employee file stays in your HRIS.

• PDFs are encrypted at rest (AES-GCM) and each document is tied to a SHA-256 digest.
• The JSON evidence contains no IP address or user-agent.
• In the sandbox and the demo, content is deleted 10 days after the PDF upload, including unfinished requests, so retrieve signed files before then.
• In production, retention is defined with your customer, and your HRIS remains the system of record for the employee file.
• Restrict access to signed documents using your HRIS roles: a manager does not always need to see every contract in their team.

Arabic, French and English

In Morocco and the Gulf, one company often employs people who read Arabic, French or English. The Khatm signing journey is available natively in all three languages, with a right-to-left interface in Arabic. The contract itself is still the PDF your customer produces; if it is bilingual, the signature covers the whole document.

Store each employee’s preferred language in their record and use it for your own emails and notifications, so the whole journey stays consistent.

Legal points to check per country

• Does local law accept electronic form for this type of contract, or does it require a paper original, an administrative stamp or a registration?
• Do contracts for foreign employees follow a specific process, such as a visa or registration with an authority?
• What level of signer identification is expected, and which certificate should be used in production?
• Which retention period applies to the contract and its evidence?

In Morocco as in Saudi Arabia, the UAE, Qatar or Oman, the answers can differ from one document to another. Khatm is not a qualified trust service provider and does not issue certificates; no national identity such as Nafath or UAE Pass is included by default. In production, signer identity and the certificate come from your customer’s identity provider and from their PKI, HSM or trust service provider. Electronic signature in Morocco

Putting it into practice with Khatm

PDF signing built into your software, under your brand, in Arabic, French and English. Test in the sandbox; we guide you all the way to production.

1. Try the demo: upload a sample contract, add an employee and an HR director, and get a PAdES-signed PDF back. The “unknown identity” warning in your PDF reader is expected, because the demo uses a self-signed test certificate.
2. Build in the sandbox: get a sandbox key (`khatm_test_…`), connect one HRIS event to request creation, then handle the completion webhook.
3. Prepare production with Khatm: scoping, adapting the flow to your brand, connecting signer identity and your customer’s certificate, RFC 3161 timestamps when the provider supplies them, and retention defined with you.

To go further, read the API documentation and the implementation page. Try the demo API documentation Implementation

General information, not legal advice. Confirm the requirements for your transaction with the appropriate adviser or receiving authority.