Notification channels

Notification channels send approval requests and other events to email, Slack, Telegram, WhatsApp, or your own webhook. Only email links and the Conto dashboard, including the dashboard assistant, decide payment approvals. Decisions also fire approval.approved and approval.denied event webhooks.

How it works

When a payment needs approval, Conto sends approval.requested to every active channel subscribed to it. Channels deliver independently, and temporary delivery failures are retried. Email and dashboard decisions follow the same approval rules and appear in the same audit history. For how requests are matched, decided, and executed, see Approvals. New organizations start with an Owner email channel that sends approval requests to the owner. Change it under Settings > Event Delivery.

Supported channels

Channel	Delivery	How approvers act
Email	HTML email	Approve/Reject links to a hosted confirmation page
Slack	Block Kit message	Review in Conto button opens the dashboard
Telegram	Message with a link button	Review in Conto button opens the dashboard
WhatsApp	Text message	Review in Conto link opens the dashboard
Webhook	Signed JSON POST	Your system sends reviewers to `dashboardUrl`

Each approval message shows the agent, amount, destination address, and why the payment was held. Email shows the full address. Chat messages shorten it and link to the review.

Setting up channels

Go to Settings > Event Delivery > Notification Channels in the Conto dashboard, or use the REST API.

Choose a channel type

Click Add Channel and select the platform: Email, Slack, Telegram, WhatsApp, or Webhook.

Configure credentials

Channel	Required config
Email	Recipient email addresses (an array in the API)
Slack	Bot token (`xoxb-...`) and channel ID
Telegram	Bot token, chat ID, and webhook secret token
WhatsApp	Phone number ID, access token, recipient numbers
Webhook	HTTPS URL and a signing secret (`secret` in config)

Webhook URLs must use HTTPS and resolve to a public address. Loopback, private, link-local, .internal, and .local hosts are rejected.

Select event types

Choose which events trigger notifications:

Event	When it fires	Notes
`approval.requested`	New payment needs approval	All channel types
`approval.decided`	Someone approved or rejected	All channel types
`approval.escalated`	Request is still pending after the workflow’s `escalation.afterHours`	All channel types
`approval.expired`	Request expired without resolution	All channel types
`governance.approval.requested`	Protected governance action needs review	`WEBHOOK` channels only
`governance.approval.decided`	Protected governance action is approved or rejected	`WEBHOOK` channels only
`payment.executed`	Payment is submitted onchain	`WEBHOOK` channels only
`alert.raised`	An alert is raised at `HIGH` or `CRITICAL` severity. See alert webhooks	`WEBHOOK` channels only
`conto_pay.request.received`	A hosted Conto Pay request is sent to the payer	`WEBHOOK` channels only
`conto_pay.request.paid`	A hosted Conto Pay request is paid	`WEBHOOK` channels only
`conto_pay.request.rejected`	A hosted Conto Pay request is rejected	`WEBHOOK` channels only
`conto_pay.request.expired`	A hosted Conto Pay request expires	`WEBHOOK` channels only
`conto_pay.request.cancelled`	The payee cancels a hosted Conto Pay request	`WEBHOOK` channels only
`conto_pay.request.reminder`	The payee sends a reminder for a hosted Conto Pay request	`WEBHOOK` channels only

On email, Slack, Telegram, and WhatsApp, approval.decided and approval.expired send a short status update with a link to the request. They have no Approve or Reject actions. approval.escalated sends the approval request again to approvers who have not decided, including the workflow’s escalation targets, only while the request is still pending and unexpired. Escalation targets can then decide the request. See escalation.

Test the channel

Click the send-test button on the channel. A test message confirms delivery only. It creates no approval request, so test emails have no Approve or Reject buttons.

Run a real approval

To test the full decision flow, request a payment that requires approval, such as one above your approval threshold:

curl -X POST https://conto.finance/api/sdk/payments/request \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 500, "recipientAddress": "0x0000000000000000000000000000000000000001", "purpose": "Test approval" }'

Approve from the email confirmation page or the dashboard. Audit Logs records who decided, when, and through which channel, for example EMAIL.

Channel configuration details

Each eligible approver receives their own HTML email with unique Approve and Reject buttons.Config fields:

recipients - List of email addresses. Enter members’ sign-in emails. Conto sends approval requests only to addresses that belong to members who can approve the request. After a request escalates, that includes its escalation targets. Other addresses, such as a shared inbox, get no approval requests. Every listed address gets test messages and, if the channel subscribes to them, approval.decided and approval.expired status updates.

Clicking a button opens a browser, validates the token, and opens the hosted confirmation page. The page shows the amount, network, full destination address, agent, and purpose. A recipient name supplied by the agent is labeled as not verified. Opening the page, or a mail scanner or link preview fetching the link, does not use the token. The decision is recorded only after the approver selects Approve payment or Reject payment.

Slack

Requires a Slack app with the chat:write bot scope. Messages use Block Kit with the payment details and a Review in Conto button that opens the request in the dashboard.Config fields:

botToken - Your Slack app’s bot token (xoxb-...)
channelId - The Slack channel ID to post messages to

Setup:

Create a Slack app at api.slack.com/apps
Add the chat:write bot scope
Install the app to your workspace
Invite the bot to the target channel

Uses the Telegram Bot API to send the payment details with a Review in Conto link button.Config fields:

botToken - Your Telegram bot token from @BotFather
chatId - The chat or group ID to send messages to
secretToken - Any random string. Required when you save the channel.

Setup:

Create a bot via @BotFather
Add the bot to your group chat
Copy the chat ID into the channel config

Uses the WhatsApp Cloud API to send each recipient a free-form text message with the payment details and a Review in Conto link.Config fields:

phoneNumberId - Your WhatsApp Business phone number ID
accessToken - Permanent access token from Meta
recipientNumbers - Phone numbers in international format (e.g., +1234567890)

Setup:

Register at developers.facebook.com
Create a WhatsApp Business app
Copy the phone number ID and a permanent access token into the channel config

Webhook

Sends a signed JSON payload to any HTTPS endpoint. Approval payloads include a dashboardUrl that opens the request in Conto. They carry no approve or reject tokens, so an authenticated Conto approver makes the decision.A webhook channel is separate from the organization event webhook. See two kinds of webhooks for how their events and signatures differ.Config fields:

url - Your HTTPS endpoint URL
secret - Signing secret for HMAC verification (required)

Every delivery carries two headers:

Header	Value
`X-Conto-Timestamp`	ISO 8601 time the delivery was signed
`X-Conto-Signature`	Hex HMAC-SHA256 of `${X-Conto-Timestamp}.${rawBody}` using your channel `secret`

Verify the signature before trusting the payload. This signed input differs from Conto’s event webhooks, which sign the raw body only. Use this verifier for every notification-channel delivery (approval, payment execution, governance, alert, and Conto Pay events).

import { createHmac, timingSafeEqual } from 'crypto';

function verifyChannelWebhook(rawBody: string, timestamp: string, signature: string, secret: string) {
  const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
  const a = Buffer.from(signature, 'hex');
  const b = Buffer.from(expected, 'hex');
  return a.length === b.length && timingSafeEqual(a, b);
}

Approval payload (approval.requested, approval.decided, approval.escalated, approval.expired):

{
  "event": "approval.requested",
  "approvalRequestId": "cmm59z8k40001abcd1234efgh",
  "paymentDetails": {
    "amount": 500,
    "currency": "USDC",
    "recipientAddress": "0x5678...",
    "agentName": "Treasury Agent",
    "purpose": "Invoice INV-2041",
    "approvalReason": "This payment exceeds a per-payment limit and requires review."
  },
  "dashboardUrl": "https://conto.finance/alerts?tab=approvals&id=cmm59z8k40001abcd1234efgh",
  "timestamp": "2026-04-06T12:00:00.000Z"
}

purpose is omitted when the agent did not supply one.Payment execution payload (payment.executed): event, paymentRequestId, paymentDetails (amount, currency, recipientAddress, agentName, purpose), transaction (transactionId, transactionHash, explorerUrl, executedAt), and timestamp.

Conto Pay lifecycle webhooks

conto_pay.request.received is delivered to the payer organization. Terminal outcomes (paid, rejected, and expired), cancellations, and reminders are delivered to both the payer and payee organizations when they have matching active webhook channels. links.requestUrl opens the request review page and links.payerActionUrl opens the payer’s action page. They match the links shown in the Conto Pay inbox.

{
  "event": "conto_pay.request.paid",
  "request": {
    "id": "cmm6b2c9x0004ipr7k3mdq1zt",
    "status": "PAID",
    "amount": 250,
    "currency": "pathUSD",
    "purpose": "Invoice INV-100",
    "invoiceId": "INV-100",
    "dueDate": "2026-06-30T00:00:00.000Z",
    "expiresAt": "2026-07-01T00:00:00.000Z",
    "createdAt": "2026-06-14T12:00:00.000Z",
    "updatedAt": "2026-06-14T12:05:00.000Z",
    "direction": "incoming"
  },
  "payer": {
    "agentName": "Buyer AP Agent",
    "agentSlug": "accounts-payable",
    "organizationName": "Buyer Inc",
    "organizationSlug": "buyer-inc",
    "handle": "@buyer-inc/accounts-payable"
  },
  "payee": {
    "agentName": "Vendor AR Agent",
    "agentSlug": "accounts-receivable",
    "organizationName": "Vendor LLC",
    "organizationSlug": "vendor-llc",
    "handle": "@vendor-llc/accounts-receivable"
  },
  "links": {
    "requestUrl": "https://conto.finance/pay-requests/cmm6b2c9x0004ipr7k3mdq1zt",
    "payerActionUrl": "https://conto.finance/conto-pay?request=cmm6b2c9x0004ipr7k3mdq1zt"
  },
  "transaction": {
    "id": "cmm6b3f1a0007txn8w2hpe5kq",
    "txHash": "0xabc123",
    "status": "CONFIRMED"
  },
  "timestamp": "2026-06-14T12:05:00.000Z"
}

Use request.direction to render the event from the receiving organization’s point of view: incoming means the organization is the payer, while outgoing means the organization created the request and is waiting on the payer.

Governance approval webhooks

Webhook channels can subscribe to governance.approval.requested and governance.approval.decided for protected organization changes. Use them when an external audit, compliance, or ticketing system needs a durable record of sensitive configuration changes such as policy updates, policy rule changes, API key lifecycle actions, or freeze configuration changes. Governance approval webhooks only notify. Owners and Admins approve or reject governance requests in the Conto dashboard. For setup, protected-action selection, and the review flow, see require a second approver for changes.

{
  "event": "governance.approval.decided",
  "approvalRequest": {
    "id": "cmm6c1g7r0002gov4n8xtb3wa",
    "action": "POLICY_UPDATE",
    "resource": "policy",
    "resourceId": "cmm6c0p2d0001pol9v6kqz4re",
    "status": "APPROVED",
    "reason": "Update policy High value spend",
    "requestPayload": "{\"isActive\":false}",
    "requestedByActorType": "USER",
    "requestedByActorId": "cmm5u1req0003usr2j7mfa8ny",
    "requestedByUserId": "cmm5u1req0003usr2j7mfa8ny",
    "expiresAt": "2026-07-14T00:00:00.000Z",
    "approvedUntil": "2026-07-13T22:15:00.000Z",
    "decidedAt": "2026-07-13T22:00:00.000Z",
    "decidedByUserId": "cmm5u2adm0005usr6c1wdh3pk",
    "decisionComment": "Reviewed with security policy owner",
    "createdAt": "2026-07-13T21:55:00.000Z",
    "updatedAt": "2026-07-13T22:00:00.000Z"
  },
  "requestedBy": {
    "id": "cmm5u1req0003usr2j7mfa8ny",
    "name": "Requester",
    "email": "requester@example.com"
  },
  "decidedBy": {
    "id": "cmm5u2adm0005usr6c1wdh3pk",
    "name": "Admin",
    "email": "admin@example.com"
  },
  "organizationId": "cmm5i0org000l49h7jsyai11p",
  "timestamp": "2026-07-13T22:00:00.000Z"
}

Alert webhooks

Webhook channels can subscribe to alert.raised to receive organization alerts outside the dashboard. Conto sends every alert raised at HIGH or CRITICAL severity. LOW, MEDIUM, and WARNING alerts stay in the dashboard. Approval requests arrive as approval.requested, not alert.raised. Conto sends at most five alerts of one type per organization in each 15-minute window. Subscribing the channel is the opt-in, so alert email preferences do not affect it. Alert types include:

`alert.type`	Raised when
`TRANSACTION_FAILED`	A payment fails onchain
`PAYMENT_NEEDS_RECONCILIATION`	A payment outcome is uncertain and needs reconciliation
`PAYMENT_FAILED`	A plan invoice payment fails
`AGENT_AUTO_FROZEN`	Conto freezes an agent automatically
`FREEZE_TRIGGER_DETECTED`	A freeze threshold fires while auto-freeze is off for the agent
`FREEZE_TRIGGER_ERROR`	Conto cannot evaluate an agent’s freeze triggers
`PAYMENT_POLICY_BYPASS`	An x402 or MPP payment settled without Conto authorization
`POLICY_VIOLATION`	A payment breaks a policy
`AGENT_MANUALLY_FROZEN`	Someone freezes an agent
`CONNECTED_CARD_APPROVAL_REQUIRED`	A connected-card request needs review
`CONNECTED_CARD_MINT_RECONCILIATION`	A connected-card request stalled after a credential may have issued
`API_CALLS_WARNING`, `TRANSACTIONS_WARNING`, `VOLUME_WARNING`	Plan usage reaches 80% of a limit
`API_CALLS_CRITICAL`, `TRANSACTIONS_CRITICAL`, `VOLUME_CRITICAL`	Plan usage reaches a limit

Conto does not retry a failed alert delivery. The failure is recorded on the channel as its last error. The same alert can arrive more than once, so dedupe on alert.id.

{
  "event": "alert.raised",
  "alert": {
    "id": "cmm6d4h8s0006alt3p9rvc2xm",
    "type": "AGENT_AUTO_FROZEN",
    "severity": "CRITICAL",
    "title": "Agent \"Treasury Agent\" has been frozen",
    "message": "Agent was automatically frozen. Reason: ...",
    "agentId": "cmm5a7agt008t49h7bjqza99x",
    "transactionId": null,
    "createdAt": "2026-07-13T22:00:00.000Z"
  },
  "organizationId": "cmm5i0org000l49h7jsyai11p",
  "timestamp": "2026-07-13T22:00:01.000Z"
}

REST API

Manage channels with an organization API key: policies:read to list, policies:write to create, update, test, or delete.

# List channels
curl https://conto.finance/api/notification-channels \
  -H "Authorization: Bearer $API_KEY"

# Create a channel
curl -X POST https://conto.finance/api/notification-channels \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channelType": "SLACK",
    "name": "Treasury Channel",
    "config": { "botToken": "xoxb-...", "channelId": "C012345" },
    "eventTypes": ["approval.requested"]
  }'

# Create a governance approval webhook channel
curl -X POST https://conto.finance/api/notification-channels \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channelType": "WEBHOOK",
    "name": "Governance Audit Stream",
    "config": { "url": "https://example.com/conto/webhooks", "secret": "whsec_..." },
    "eventTypes": ["governance.approval.requested", "governance.approval.decided"]
  }'

# Test a channel
curl -X POST https://conto.finance/api/notification-channels/{id}/test \
  -H "Authorization: Bearer $API_KEY"

# Delete a channel
curl -X DELETE https://conto.finance/api/notification-channels/{id} \
  -H "Authorization: Bearer $API_KEY"

Email action token security

Action tokens secure the Approve and Reject links in approval emails.

32 bytes of cryptographic randomness, base64url-encoded
Protected at rest. Plaintext tokens are not retained after issuance
One-time use. Tokens cannot be reused after a decision is recorded
Time-limited. Tokens expire when the approval request expires (default 24 hours)
Per-user, per-action. Each approver gets separate Approve and Reject tokens
Full audit trail. Every decision records the channel, token ID, IP address, and user agent

Troubleshooting

Notifications not arriving

Check that the channel is active in Settings > Event Delivery
Review the delivery notice shown for the channel
Verify your bot token or credentials
For Slack, confirm the bot is invited to the target channel
For Telegram, confirm the bot is in the chat that matches the configured chat ID

Email link expired or already used

Email action tokens are one-time use and expire with the approval request. Once the request is resolved, by another approver or from the dashboard, its links stop working.

No approve button in Slack, Telegram, or WhatsApp

This is expected. Chat messages link to the request with Review in Conto. Approve or reject in the dashboard or from the approval email.

Get started

Integrate

Payments

Agentic commerce

Spending controls

Operate

Conto Pay

Notification channels

How it works

Supported channels

Setting up channels

Channel configuration details

Conto Pay lifecycle webhooks

Governance approval webhooks

Alert webhooks

REST API

Email action token security

Troubleshooting

Next steps

Approval workflows

Recommended policy setup

​How it works

​Supported channels

​Setting up channels

​Channel configuration details

​Conto Pay lifecycle webhooks

​Governance approval webhooks

​Alert webhooks

​REST API

​Email action token security

​Troubleshooting

​Next steps

Approval workflows

Recommended policy setup

How it works

Supported channels

Setting up channels

Channel configuration details

Conto Pay lifecycle webhooks

Governance approval webhooks

Alert webhooks

REST API

Email action token security

Troubleshooting

Next steps