Approval notifications

When an agent sends a request that a policy authorizes only with a signed approval, such as a refund that needs a manager, Parmana refuses it and the agent must send a new request with the approval attached. Approval notifications tell the approver right away. Parmana sends a signed approval.needed event to a URL you choose, with exactly what the approver needs to sign.

When an event is sent

Parmana sends one event when all of these hold:

The request was refused by the policy’s own rules, or because an attached approval did not verify.
The policy declares approvalSignals.
Evaluating the same policy, with every declared approval signal set to true, authorizes the request.

The third condition means an event only goes out when an approval would actually help. A refund refused for a failed fraud check, or above the policy’s maximum, sends nothing, because a manager’s signature would not change the outcome. Requests refused before the policy runs, such as a bad API key or a request whose signals do not match its own parameters, send nothing.

Set it up

Create an endpoint

Any HTTPS endpoint that accepts a JSON POST and answers 2xx within 3 seconds: a small function of your own, a Slack workflow webhook behind a relay, or an automation service.

Generate a secret

openssl rand -hex 32

Store it where your endpoint can read it. You will verify every event with it.

Configure Parmana

Set both variables on the deployment, then redeploy:

APPROVAL_WEBHOOK_URL=https://hooks.example.com/parmana-approvals
APPROVAL_WEBHOOK_SECRET=<the secret>

With PARMANA_SECRETS_PROVIDER=aws-secrets-manager, APPROVAL_WEBHOOK_SECRET is the name or ARN of the secret instead of its value. Setting only one of the two stops the server at startup. The URL must be https outside NODE_ENV=test and development.

Send a test request

Send a request the policy refuses only for want of an approval, for example a refund with managerApproved: false and every other fact true. Your endpoint receives an event.

The event

{
  "type": "approval.needed",
  "occurredAt": "2026-09-29T10:15:02.114Z",
  "businessTransactionId": "5f0c2a7e-3d7b-4d0e-9a55-2f6d8b1c4e90",
  "decisionId": "a91e6c1d-0b8f-4f3a-8e57-6f2d1c9b7a44",
  "action": "paytm:refund",
  "target": "paytm://orders/ORD-1042",
  "policyId": "customer-refund",
  "policyVersion": "1.2.0",
  "reason": "No rule matched.",
  "submittedBy": "refund-agent",
  "approvals": [
    { "signal": "managerApproved", "resourceId": "ORD-1042", "value": 75000 }
  ]
}

string

required

Always approval.needed.

string

required

When the request was refused, ISO 8601 UTC.

string

required

The refused request. Its Refusal Record has the full decision.

string

required

The refusal decision.

string

required

The action that needs approval, such as paytm:refund. Sign with this as capability.

string

required

The request’s target.

string

required

The policy that refused it.

string

required

Its version.

string

The refusal reason from the policy.

string

The caller that sent the request, when known.

object[]

required

One entry per approval the policy declares.

Show properties

string

required

The approval signal, such as managerApproved. The agent sets it to true on the new request.

string

What the approval must name, read from the request at the policy’s resourceId path. Sign with this as resourceId. Absent if the request did not carry it.

number

The amount the approval must cover, read at the policy’s value path. Sign with at least this as the maximum amount. Absent when the policy declares no amount.

The event carries only what the approver needs. Other request parameters and signals are not sent; look them up by businessTransactionId if you need them.

Verify the signature

Every event has two headers:

Header	Value
`parmana-webhook-timestamp`	Unix seconds when it was sent
`parmana-webhook-signature`	`v1=` and the lowercase hex HMAC SHA256 of `<timestamp>.<raw body>`, keyed with the secret

Verify against the raw request body, before parsing it, compare in constant time, and refuse a timestamp more than 5 minutes old so a captured event cannot be replayed later.

import { createHmac, timingSafeEqual } from "node:crypto";
import express from "express";

const app = express();

app.post(
  "/parmana-approvals",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const timestamp = req.header("parmana-webhook-timestamp") ?? "";
    const signature = req.header("parmana-webhook-signature") ?? "";
    const body = req.body.toString("utf8");

    const expected =
      "v1=" +
      createHmac("sha256", process.env.APPROVAL_WEBHOOK_SECRET!)
        .update(`${timestamp}.${body}`)
        .digest("hex");

    const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
    const valid =
      expected.length === signature.length &&
      timingSafeEqual(Buffer.from(expected), Buffer.from(signature));

    if (!fresh || !valid) {
      res.status(400).end();
      return;
    }

    const event = JSON.parse(body);
    // Hand off to a queue or notify the approver, then answer fast.
    res.status(204).end();
  },
);

import hashlib
import hmac
import json
import os
import time

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["APPROVAL_WEBHOOK_SECRET"].encode()


@app.post("/parmana-approvals")
def approvals():
    timestamp = request.headers.get("parmana-webhook-timestamp", "")
    signature = request.headers.get("parmana-webhook-signature", "")
    body = request.get_data()  # raw bytes, before parsing

    expected = "v1=" + hmac.new(
        SECRET, timestamp.encode() + b"." + body, hashlib.sha256
    ).hexdigest()

    fresh = timestamp.isdigit() and abs(time.time() - int(timestamp)) < 300
    if not fresh or not hmac.compare_digest(expected, signature):
        abort(400)

    event = json.loads(body)
    # Hand off to a queue or notify the approver, then answer fast.
    return "", 204

From event to approval

The approver signs exactly what the event names:

npx tsx scripts/sign-approval.ts \
  --private-key-file ~/.parmana/manager-priya__manager-priya-key-1.private.pem \
  --approver-id manager-priya --key-id manager-priya-key-1 \
  --capability "$ACTION" --resource-id "$RESOURCE_ID" --max-amount "$VALUE" \
  --out approval.json

import { signApproval } from "@parmana/sdk";

const [needed] = event.approvals;
const approval = signApproval({
  privateKeyPem,
  approverId: "manager-priya",
  keyId: "manager-priya-key-1",
  capability: event.action,
  resourceId: needed.resourceId,
  ...(needed.value !== undefined ? { maxAmount: needed.value } : {}),
});

from parmana.crypto import sign_approval

needed = event["approvals"][0]
approval = sign_approval(
    private_key_pem=private_key_pem,
    approver_id="manager-priya",
    key_id="manager-priya-key-1",
    capability=event["action"],
    resource_id=needed["resourceId"],
    max_amount=needed.get("value"),
)

The agent then sends a new request, with a new businessTransactionId, the approval signal set to true, and the approval in signals.approvalArtifact. See Human approval.

An event says a request is waiting. It is not an instruction to approve it. The approver decides, on their own machine, with their own key; your endpoint should never sign approvals automatically.

Delivery

Behavior	Detail
Attempts	One. There is no retry.
Timeout	3 seconds. Answer quickly and do slow work afterwards.
Success	Any `2xx`. Anything else, a timeout, a redirect, or a network error is logged as `approval_needed_notification_failed`.
Effect	None on the request. It is refused either way, and the agent’s response is the same.
Ordering	Events are sent in the order requests are refused, but may arrive out of order.
Duplicates	Each refused request sends at most one event. An agent that retries sends one per request.

Because delivery is best effort, the Refusal Records remain the complete list of waiting requests. For a daily sweep, see Review refused requests.

Test locally

Point the webhook at a local listener and run Parmana in development:

NODE_ENV=development \
APPROVAL_WEBHOOK_URL=http://127.0.0.1:4000/parmana-approvals \
APPROVAL_WEBHOOK_SECRET=local-test-secret \
npm run dev

http is accepted only in development and test.

Reference

Variable	Required	Description
`APPROVAL_WEBHOOK_URL`	With the secret	Where events are sent. `https` outside development and test.
`APPROVAL_WEBHOOK_SECRET`	With the URL	HMAC key, or a secret reference with a secrets provider.

Build with Parmana

Verify and audit

Worked examples

Approval notifications

When an event is sent

Set it up

The event

Verify the signature

From event to approval

Delivery

Test locally

Reference

​When an event is sent

​Set it up

​The event

​Verify the signature

​From event to approval

​Delivery

​Test locally

​Reference

When an event is sent

Set it up

The event

Verify the signature

From event to approval

Delivery

Test locally

Reference