React to hire and termination

Instead of periodic polling, subscribe to events and update your copy as soon as an employee is created or terminated at Keruen LLP. An event only tells you what changed — you fetch the current data with your key.

Subscriptions are managed by the webhooks:manage scope, and re-reading records requires employees:read.

Subscribe to events

Create an endpoint for employee hires and deletions. The secret in the response is shown once — store it in a secrets manager; it verifies the signature of every delivery.

curl -X POST -H "X-API-Key: ddp_YOUR_KEY" -H "Content-Type: application/json" \
  https://app.doodocs.kz/api/developer/v1/webhook_endpoints \
  -d '{
    "url": "https://keruen.example/hooks/doodocs",
    "event_types": ["employee.changed", "employee.deleted"]
  }'

employee.changed combines creation and change: there is deliberately no separate created. Handle the event as an upsert — the source cannot always reliably tell an employee’s first appearance from a later change.

Verify the signature

Every delivery carries the Doodocs-Signature: t=<unix>,v1=<hex> header, where v1 is HMAC-SHA256(secret, "{t}.{request body}") in hex. Reject the request if the signature does not match or t is older than five minutes (replay protection).

import hashlib, hmac, time

def verify(secret: str, header: str, body: bytes) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t, v1 = parts["t"], parts["v1"]
    if abs(time.time() - int(t)) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

Re-read and upsert

The payload contains only employee_id. Fetch the record with your key — that way the key’s scope and field redaction apply to the data, and personal data does not leave for an external URL.

curl -H "X-API-Key: ddp_YOUR_KEY" \
  "https://app.doodocs.kz/api/developer/v1/employees/3f2a9c7e-…?expand=person&expand=department"

employee.changed → re-read GET /employees/{employee_id} and upsert by id.
employee.deleted → a re-read returns 404 EMPLOYEE_NOT_FOUND. Do not treat this as an error: the event is self-contained, so mark the employee deleted.

The handler

Deduplicate on the event id (delivery is at-least-once), respond 2xx quickly, and push the heavy work to the background.

import json, requests

BASE = "https://app.doodocs.kz/api/developer/v1"
HEADERS = {"X-API-Key": "ddp_YOUR_KEY"}
SECRET = "…"                                   # the stored subscription secret

def handle(headers, body: bytes):
    if not verify(SECRET, headers["Doodocs-Signature"], body):
        return 401
    event = json.loads(body)
    if seen(event["id"]):                     # deduplicate by event id
        return 200

    employee_id = event["data"]["employee_id"]
    if event["type"] == "employee.deleted":
        mark_deleted(employee_id)
        return 200

    resp = requests.get(f"{BASE}/employees/{employee_id}", headers=HEADERS,
                        params={"expand": ["person", "department"]})
    if resp.status_code == 404:               # race: deleted between the event and the re-read
        mark_deleted(employee_id)
    else:
        upsert(resp.json())                   # employee.changed = create + update
    return 200

An employee may be deleted between employee.changed and your re-read — then GET /employees/{id} returns 404. Treat this as a deletion, not a failure.

Sync all employees

Initial export and a full re-read to reconcile deletions.

Webhooks

All event types, delivery reliability, and debugging.

Getting started

Employees

Documents

Recipes

React to hire and termination

The handler

Next

Sync all employees

Webhooks

​The handler

​Next

Sync all employees

Webhooks

The handler

Next