Let your agent ask a human.
Agents propose, humans approve. Before an AI agent deploys, refunds or deletes, it asks the right people on the channel they already use, and gets a signed answer back.
An approval request is a yes/no question sent as a notification. The people you name get it in their in-app inbox with Approve and Reject, and by email or push with a link to a page Notify hosts. The first answer decides. Your agent reads it from the API, or your backend gets the signed approval.resolved webhook. Unanswered requests time out, and every step is in the request's trail and your workspace audit log.
1
An approval type
Any notification type becomes an approval type with approval: whether a reason is required, how long people have to answer, and what an unanswered request becomes. Keep timeout_outcome: "expired" unless an unanswered request may safely go ahead. Making it critical means muted categories and quiet hours don't hide the question.
Templates get approval.title, approval.body and approval.requester.name; email and push templates also get each approver's own signed approval.url, approval.approve_url and approval.reject_url. Inbox items get Approve and Reject buttons on their own.
await notify.notificationTypes.replaceByKey("deploy.approval", {
name: "Deploy approval",
category_key: "operations",
routing: { always: ["inbox", "email"], fallback: [] },
critical: true, // reaches people who muted the category, and during quiet hours
approval: {
reason: "required_on_reject",
default_expires_in_seconds: 3600,
timeout_outcome: "expired", // nobody answered: do not act
},
templates: [
{ channel: "inbox", locale: "en", body: { title: "{{approval.title}}", body: "{{approval.requester.name}} asks: {{approval.body}}" } },
{ channel: "email", locale: "en", body: { mail_template_name: "approval-request" } },
],
});2
Ask, then wait or poll
wait_seconds (up to 15) waits for a quick answer in the same call; after that, poll with a long poll. Use an Idempotency-Key per action so a retried agent step never asks twice. Only approved means go.
const request = await notify.approvals.create(
{
type: "deploy.approval",
approvers: ["user_123", "user_456"], // the first answer decides
title: "Deploy api v2.14 to production?",
body: "3 migrations, 41 commits. Rollback: redeploy v2.13.",
requester: { kind: "agent", name: "Deploy bot", id: "run_8f2c" },
metadata: { deployment_id: "dep_91" }, // comes back in the webhook
expires_in_seconds: 1800,
wait_seconds: 15, // wait for a quick answer in this call
},
{ idempotencyKey: "deploy:dep_91" }, // a retry never asks twice
);
let approval = request;
while (approval.status === "pending") {
approval = await notify.approvals.retrieve(request.id, { wait_seconds: 15 }); // long poll
}
if (approval.status === "approved") {
// act, then tell the people who approved
} else {
console.log(`Not deploying: ${approval.status}`, approval.reason);
}| status | What it means |
|---|---|
approved | An approver pressed Approve. Act. |
rejected | An approver pressed Reject, maybe with a reason. Do not act. |
expired | Nobody answered by expires_at (the default timeout outcome). Do not act. |
cancelled | The requester withdrew it. |
3
From an MCP agent
Agents connected to the ProductCraft MCP server get notify_request_approval (ask, and optionally wait), notify_get_approval (poll, with a wait), notify_list_approvals and notify_cancel_approval. There is deliberately no tool to answer a request: the agent that asks can never approve itself. The request shows the agent as the requester, and the audit log names the connection.
4
Get the answer pushed to you
Subscribe an endpoint to approval.resolved in Notify › Webhooks. It is signed (Standard Webhooks), retried, and replayable, and carries your metadata back so you can resume the action you asked about.
// app/webhooks/notify/route.ts
import { Notify } from "@productcraft/notify";
const notify = new Notify(); // reads PRODUCTCRAFT_NOTIFY_WEBHOOK_SECRET
export async function POST(req: Request): Promise<Response> {
const event = await notify.webhooks.unwrap({ payload: await req.text(), headers: req.headers });
if (event.type === "approval.resolved") {
const { approval_id, status, decided_by, reason, metadata } = event.data;
console.log(approval_id, status, decided_by, reason, metadata);
}
return new Response(null, { status: 204 });
}5
The approver's side
<NotifyInbox/> shows approval items with a reason box and Approve and Reject. <NotifyApproval/> renders one anywhere else. Without React, call client.approvals.decide(id, "approve") from @productcraft/notify-js. From an email or push, the link opens the hosted page; no sign-in, and opening it never answers.
"use client";
import { NotifyApproval, NotifyInbox, useInbox } from "@productcraft/notify-react";
// <NotifyInbox/> already renders approval items with Approve / Reject and a reason box.
export function Bell() {
return <NotifyInbox />;
}
// Or put pending requests on a page of their own.
export function PendingApprovals() {
const { items } = useInbox({ category: "operations" });
return (
<ul>
{items.map((item) => (
<li key={item.id}>
<strong>{item.title}</strong>
<NotifyApproval item={item} />
</li>
))}
</ul>
);
}6
What you can show an auditor
GET /approvals/{approval_id}: who asked (agent, key or user), who was notified, every answer including refused ones (too late, not an approver, missing reason), the outcome and the webhook. Notify › Approvals shows the same.- The workspace audit log:
notify.approval.requested,notify.approval.decided,notify.approval.expired,notify.approval.cancelled. - The message log: every delivery of the question, per channel.