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, with exactly what they need to sign, in one or both of two ways:

Channel	You set	Best for
Email	`APPROVAL_EMAIL_TO`, and the Resend integration	A person’s inbox, with nothing to host. Set up email.
Webhook	`APPROVAL_WEBHOOK_URL`, `APPROVAL_WEBHOOK_SECRET`	Your own system: Slack, a ticket, a queue. Set up the webhook.

Both carry the same facts and are sent under the same rule, below.

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.

Email

Parmana emails each event through Resend, from a domain you own.

Add Resend to the Vercel project

From the repository, linked to the project with npx vercel link:

npx vercel integration add resend/resend-email --environment production \
  -m domain=notify.example.com -m region=us-east-1

Accept Resend’s terms in the browser when asked. This sets RESEND_API_KEY and RESEND_EMAIL_DOMAIN on the project. Use a subdomain, such as notify.example.com, so its records cannot affect other mail on your domain.

Verify the domain

Resend lists three DNS records for the domain: a DKIM TXT record at resend._domainkey.notify, and an MX and a TXT (SPF) record at send.notify. Add them at your DNS provider. Emails are refused until the domain shows Verified in Resend.

Name the recipients

npx vercel env add APPROVAL_EMAIL_TO production

One address, or several separated by commas. Then redeploy.

Emails come from Parmana approvals <approvals@<RESEND_EMAIL_DOMAIN>>, or from APPROVAL_EMAIL_FROM if you set it. A missing Resend key, a missing sender, or an address that is not valid stops the server at startup, so a broken setup cannot fail silently. A notification email looks like this:

Subject: Approval needed: paytm:refund ORD-1042 up to 75000

A request was refused because it needs a signed approval.

Action:       paytm:refund
Target:       paytm://orders/ORD-1042
Policy:       customer-refund 1.2.0
Transaction:  5f0c2a7e-3d7b-4d0e-9a55-2f6d8b1c4e90
Refused at:   2026-09-29T10:15:02.114Z
Sent by:      refund-agent

To approve, sign on your own machine:
  capability  paytm:refund
  resourceId  ORD-1042
  maxAmount   75000
  signal      managerApproved

Then send the approval to the agent, which resends the request with it.
If you do not approve, do nothing: the request stays refused.

Each refusal sends at most one email: the send carries the idempotency key approval-needed/<decisionId>, so a retried send is not delivered twice. Delivery follows the same rules as the webhook: one attempt, a failure is logged and never changes the refusal.

Webhook

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

Email

Webhook

Set it up

The event

Verify the signature

From event to approval

Delivery

Test locally

Reference

​When an event is sent

​Email

​Webhook

​Set it up

​The event

​Verify the signature

​From event to approval

​Delivery

​Test locally

​Reference

When an event is sent

Email

Webhook

Set it up

The event

Verify the signature

From event to approval

Delivery

Test locally

Reference