coding-best-practices

Coding Best Practices — Rossum Serverless Functions

Overview

Audit custom Python hook code against Rossum-specific and general best practices. Rossum serverless functions run as stateless, event-driven Python 3.12 compute (AWS Lambda style). Issues here cause silent failures, data corruption, or security incidents.

---

Step 1: Find Custom Hook Files

In a prd project, hook .py files live alongside their .json counterparts in <org>/<env>/hooks/. Only hooks that have a .py file contain custom code — the rest are no-code Rossum extensions.

find . -name "*.py" -path "*/hooks/*"

---

Step 2: Evaluate Each Hook

Work through every checklist item. Flag violations in the output format at the end.

2.1 — Consider Whether Custom Code Is Needed

Before reviewing code quality, ask: could this hook be replaced by a no-code alternative?

• Rossum Store — pre-built extensions (MDH matching, export pipelines, SFI)
• Formula Fields — simple field transformations and calculations
• Export Pipeline — routing, filtering, payload construction

Flag hooks where the entire logic could be replaced by a no-code extension.

---

2.2 — Security (Critical)

No hardcoded credentials Passwords, API keys, client secrets must never appear in code. Use payload["secrets"] and define secrets_schema in the hook JSON (outside a prd2 tree, set it via the rossum_create_hook / rossum_patch_hook MCP tools — key names only, a human enters the values):

// hook.json — secrets_schema
{
  "type": "object",
  "properties": {
    "username": { "type": "string", "minLength": 1, "description": "Service account login" },
    "password": { "type": "string", "minLength": 1, "description": "Service account password" }
  },
  "additionalProperties": false
}

The API enforces this shape: top-level keys other than type/properties/additionalProperties are rejected (no $schema, no required), every declared property must be type string, and additionalProperties must be present — HTTP 400 otherwise. Use false (as above) for a fixed credential set; for hooks whose code writes its own secrets at runtime (e.g. OAuth token caches), use "additionalProperties": {"type": "string"} instead, since a closed schema would reject those writes.

# Bad
auth=("api_user", "Hardcoded123")

# Good
auth=(payload["secrets"]["username"], payload["secrets"]["password"])