Notification Channels

Notification channels send approval requests and webhook lifecycle events to external platforms. Approvers can approve or reject directly from their email inbox, Slack workspace, Telegram chat, or WhatsApp conversation. Webhook channels can also receive machine-readable payment execution and governance approval events for agents, compliance tools, and back-office systems.

How It Works

Payment triggers approval workflow
  → Conto generates secure, one-time action tokens
    → Notifications sent to all configured channels
      → Approver clicks Approve/Reject
        → Token is validated and consumed
          → Same approval logic as the dashboard

Every external decision follows the same approval rules as a dashboard decision and appears in the same audit history. When a decision reaches the required approval count, Conto submits payments from managed wallets. The resulting transaction hash and explorer URL are available from the approval review; payment.executed remains the lifecycle event for downstream webhook consumers. External and smart-contract wallets still use their manual execution flow. When a policy requires approval and no custom workflow matches, Conto creates a one-review request for an organization Owner, Admin, or Manager. The dashboard alert and configured notification channels reference the same reviewable request.

General Store Email Actions

General Store emails use the same hashed action-token infrastructure for customer order approval, merchant Accept and Ready actions, customer status links, and disabling Store auto-pay. Order actions are scoped to the order and intended recipient, expire automatically, and are consumed atomically when used so a replay cannot repeat a lifecycle transition. Stripe Connect onboarding uses a separate merchant-scoped, time-limited renewal token. It does not contain Stripe credentials and cannot edit a merchant or enable payouts. Its only authority is to request a fresh single-use Stripe Account Link for the same merchant when an emailed onboarding link expires. Stripe account.updated events and an explicit admin sync remain the source of truth for charges and payout readiness.

Supported Channels

Channel	Delivery	How Approvers Act
Email	Rich HTML via Resend	Click Approve/Reject button links
Slack	Block Kit message with buttons	Click interactive action buttons
Telegram	Message with inline keyboard	Tap inline keyboard buttons
WhatsApp	Interactive button message	Tap reply buttons
Webhook	JSON POST with tokens	POST tokens back to Conto API

Setting Up Channels

Go to Settings > 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

Each channel type requires different configuration:

Channel	Required Config
Email	Comma-separated recipient email addresses
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 targets must resolve to public addresses. Conto rejects loopback, private, link-local, and other internal-only destinations. In production, webhook channels must use HTTPS.

Select event types

Choose which events trigger notifications:

Event	When It Fires	Notes
`approval.requested`	New payment needs approval	Available on all channel types
`approval.decided`	Someone approved or rejected	Available on all channel types
`approval.escalated`	Request escalated after timeout	Available on all channel types
`approval.expired`	Request expired without resolution	Available on 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
`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

Test the channel

Click the test button to send a sample notification and verify your configuration.

Channel Configuration Details

Uses Resend to deliver rich HTML emails. Each eligible approver receives their own email with unique Approve and Reject buttons.Config fields:

recipients - List of email addresses. Only addresses matching eligible approvers receive actionable emails.

Clicking a button opens a browser, validates the token, submits the decision, and shows a confirmation page.

Slack

Requires a Slack app with the chat:write bot scope. Messages use Block Kit with payment details and interactive Approve/Reject buttons.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
Set the interactivity request URL to https://conto.finance/api/webhooks/slack
Set SLACK_SIGNING_SECRET in your Conto environment

When an approver clicks a button, Slack sends the interaction to Conto. The message is updated to show the result.

Uses the Telegram Bot API to send messages with inline keyboard buttons.Config fields:

botToken - Your Telegram bot token from @BotFather
chatId - The chat or group ID to send messages to
secretToken - Required webhook secret. Conto requires Telegram to send the matching x-telegram-bot-api-secret-token header on every callback.

Setup:

Create a bot via @BotFather
Set the webhook URL: https://api.telegram.org/bot{token}/setWebhook?url=https://conto.finance/api/webhooks/telegram
Include Telegram’s secret_token option when calling setWebhook
Add the bot to your group chat

Conto only accepts interactive callbacks for the configured chatId. Telegram callbacks must also include the matching secret header before approval tokens are processed.When an approver taps a button, the message updates to show the result.

Uses the WhatsApp Cloud API to send interactive button messages.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
Set the webhook URL to https://conto.finance/api/webhooks/whatsapp
Set WHATSAPP_APP_SECRET and WHATSAPP_VERIFY_TOKEN in your Conto environment
Subscribe to the messages webhook field

Webhook

Sends a signed JSON payload to any HTTPS endpoint. Use this for custom integrations that need to review and submit approval decisions.Config fields:

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

Every delivery is signed: the X-Conto-Signature header carries an HMAC-SHA256 of ${timestamp}.${rawBody} computed with your channel secret. Verify it before trusting the payload.Validation rules:

The destination must resolve to a public IP address
Private, loopback, link-local, and .internal / .local hosts are rejected
In production, only https:// webhook targets are accepted

Payload format:

{
  "event": "approval.requested",
  "approvalRequestId": "clxyz123...",
  "paymentDetails": {
    "amount": 500,
    "currency": "USDC",
    "recipientAddress": "0x5678...",
    "agentName": "Treasury Agent"
  },
  "tokens": {
    "approve": "base64url-token",
    "reject": "base64url-token"
  },
  "actionUrl": "https://conto.finance/api/approvals/action",
  "timestamp": "2026-04-06T12:00:00Z"
}

To submit a decision, POST the token back to the actionUrl:

curl -X POST https://conto.finance/api/approvals/action \
  -H "X-Action-Token: base64url-token" \
  -H "Content-Type: application/json" \
  -d '{"comment": "Approved via external review system"}'

Conto Pay Lifecycle Webhooks

Webhook channels can subscribe to hosted Conto Pay request lifecycle events: conto_pay.request.received, conto_pay.request.paid, conto_pay.request.rejected, and conto_pay.request.expired. The received event is delivered to the payer organization. Terminal outcomes (paid, rejected, and expired) are delivered to both the payer and payee organizations when they have matching active webhook channels. Each Conto Pay webhook payload includes absolute hosted links for the request review page and the payer action page. These match the copyable links shown in the Conto Pay activity inbox and hosted request review screens, so external systems and human operators can refer to the same URL.

{
  "event": "conto_pay.request.paid",
  "request": {
    "id": "ipr_...",
    "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/ipr_...",
    "payerActionUrl": "https://conto.finance/conto-pay?request=ipr_..."
  },
  "transaction": {
    "id": "tx_...",
    "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 events for protected organization changes: governance.approval.requested and governance.approval.decided. Use these events 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 are notification-only. Owners and admins still approve or reject requests from the Conto dashboard. For dashboard setup, protected-action selection, and the in-product review flow, see Governance Approvals.

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

REST API

Manage channels programmatically:

# 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", "approval.decided"]
  }'

# 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"

Action Token Security

Action tokens are the core security mechanism for external approvals.

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

Store order approval emails use the same one-time token model. When a connected agent starts a General Store checkout that requires customer approval, Conto emails the customer order-bound Approve and Decline links. Approval opens hosted checkout for that order; decline cancels the approval-pending order and releases the reserved spend.

Webhook Payload Validation

Inbound webhook payloads from Slack, Telegram, and WhatsApp are validated against typed Zod schemas before processing. Malformed payloads are rejected with a 400 response and never reach handler logic. Signature verification (HMAC) still runs first for all three providers regardless of payload shape.

Delta decision callbacks

Organizations using Delta receive a signed approval.requested webhook with the approval reference and the payment and invoice fields required for verification. Verify the X-Conto-Signature over ${X-Conto-Timestamp}.${rawBody} before acting on the request. See Delta Verification Setup and the Delta End-to-End Test for the complete integration sequence. After verification, submit the decision to the decision callback URL provisioned during Delta onboarding. Use the approval reference from the webhook:

POST {decisionCallbackUrl}
X-Conto-Timestamp: 2026-05-26T18:00:00Z
X-Conto-Signature: <hex HMAC-SHA256 of `${timestamp}.${rawBody}` using config.secret>
Content-Type: application/json

{
  "decision": "APPROVED",
  "comment": "Invoice and recipient verified",
  "verification": {
    "proofType": "delta_signed",
    "proofRef": "https://delta.example/proofs/abc",
    "evidenceHash": "...",
    "reason": "OK"
  }
}

The response returns recorded, idempotent, the approval and payment references, a customer status, and status URLs. A pending response includes an await_more_approvals next action. Retrying the same signed decision is safe; a conflicting decision returns DECISION_CONFLICT. Subscribe to payment.executed when the verifier also needs the settlement transaction reference, hash, explorer URL, and execution time for reconciliation.

Start

Products

Build

Guides

Reference

Changelog

Notification Channels

Notification Channels

How It Works

General Store Email Actions

Supported Channels

Setting Up Channels

Channel Configuration Details

Conto Pay Lifecycle Webhooks

Governance Approval Webhooks

REST API

Action Token Security

Webhook Payload Validation

Delta decision callbacks

Next Steps

Approval Workflows

Securing Agents

​Notification Channels

​How It Works

​General Store Email Actions

​Supported Channels

​Setting Up Channels

​Channel Configuration Details

​Conto Pay Lifecycle Webhooks

​Governance Approval Webhooks

​REST API

​Action Token Security

​Webhook Payload Validation

​Delta decision callbacks

​Next Steps

Approval Workflows

Securing Agents

Notification Channels

How It Works

General Store Email Actions

Supported Channels

Setting Up Channels

Channel Configuration Details

Conto Pay Lifecycle Webhooks

Governance Approval Webhooks

REST API

Action Token Security

Webhook Payload Validation

Delta decision callbacks

Next Steps