Webhooks

Conto POSTs signed JSON events to your HTTPS endpoint.

Two kinds of webhooks

Conto has two webhook systems. This page covers event webhooks.

	Event webhook (this page)	Notification channel webhook
Set up in	Settings > Event Delivery > Organization webhook, or an agent `callbackUrl`	Settings > Event Delivery > Notification Channels > Add Channel, or `POST /api/notification-channels`
Use it for	Every event to one endpoint, for your backend or audit feed	Approval requests and other events you subscribe the channel to
Events	All event types, including `approval.approved` and `approval.denied`	Events you pick, such as `approval.requested` and `approval.decided`
Signature input	The raw body, with the secret Conto generates	`timestamp.rawBody`, with the `secret` you set on the channel
Headers	`X-Conto-Signature`	`X-Conto-Signature` and `X-Conto-Timestamp`

Both sign with HMAC-SHA256 and send X-Conto-Signature, but they sign different input, so each needs its own verifier.

Test a local handler

With the Conto CLI installed, use the same development signing secret in your handler and terminal:

export CONTO_WEBHOOK_SECRET="your-local-development-secret"
npx @conto_finance/create-conto-agent webhooks test http://localhost:8080/webhooks/conto --json

This sends one signed synthetic payment.confirmed event with data.test: true and a test_ payment ID. It reports the HTTP status and latency, creates no Conto payment, and requires no API key. The command accepts only loopback URLs and does not follow redirects. It tests your handler’s signature and payload processing, not whether hosted delivery can reach your endpoint. If you installed the package globally, conto webhooks test <url> runs the same command.

Setup

Go to Settings > Event Delivery in the dashboard
Enter your HTTPS endpoint URL
Copy the generated signing secret. Your handler uses it to verify payloads

Webhook URLs must use HTTPS. HTTP, loopback hosts, and private IP ranges are blocked for security (SSRF protection).

Event types

Event	Fires when
`payment.requested`	A `payments/request` call is evaluated (external-wallet `approve` sends no `payment.requested`, `approved`, or `denied` events)
`payment.approved`	A payment passes policy evaluation or its approval is granted
`payment.denied`	A payment is blocked by policy or rejected in review
`payment.executed`	A managed payment is submitted onchain or a test payment is simulated
`payment.confirmed`	A payment is confirmed onchain
`payment_request.created`	An agent-to-agent payment request is created
`agent.frozen`	An agent is frozen
`agent.unfrozen`	An agent is restored to active status
`policy.created`	A policy is created
`policy.updated`	A policy is updated
`policy.deleted`	A policy is deleted
`approval.approved`	A payment approval is granted
`approval.denied`	A payment approval is denied
`governance.approval.decided`	A sensitive change (separation of duties) is approved or denied

Alerts are not sent to this webhook. To receive HIGH and CRITICAL alerts off the dashboard, subscribe a webhook notification channel to alert.raised.

Governance events for SIEM and GRC

policy.*, approval.*, and governance.approval.decided stream policy and approval-decision activity to your webhook for your own audit trail. Payloads differ by event family:

Policy events (policy.created / updated / deleted) carry policyId, name, and policyType, never the underlying rule values. policy.created also includes scope, priority, and rulesCount. policy.updated includes isActive.
Approval events (approval.approved / approval.denied) carry approvalRequestId, paymentRequestId, amount, and decision (APPROVED or DENIED). Agent callback deliveries add agentId.
governance.approval.decided (separation-of-duties decisions on sensitive changes) carries governanceApprovalRequestId, action, resource, resourceId, and decision.

They are delivered best-effort after the change commits, so a delivery failure never blocks the change itself.

Payload format

Every webhook POST includes these headers and a JSON body:

Headers

Header	Description
`X-Conto-Event`	Event type (e.g., `payment.confirmed`)
`X-Conto-Timestamp`	ISO 8601 timestamp of the event
`X-Conto-Signature`	Hex HMAC-SHA256 of the raw body
`X-Conto-Delivery-Id`	Stable ID for this delivery, the same on every retry
`X-Conto-Delivery-Attempt`	Attempt number (1, 2, or 3)

Body

{
  "event": "payment.confirmed",
  "timestamp": "2026-04-07T12:00:00.000Z",
  "data": {
    "paymentId": "cmm5h0req000l49h7irxzh11p",
    "amount": 50,
    "transactionHash": "0xabc...",
    "transactionId": "cmm5g0txn000l49h7hqwyg11p",
    "settlementMode": "live",
    "organizationId": "cmm5i0org000l49h7jsyai11p"
  },
  "deliveryId": "5b1f7c2e-8d4a-4f3b-9a61-2c7e0d9f4b18"
}

Organization webhook deliveries add organizationId to data. Agent callback deliveries add agentId instead.

Verifying signatures

Conto signs every payload with your webhook secret using HMAC-SHA256. Verify the signature to confirm the request came from Conto. These event webhooks sign the raw request body only. Notification-channel webhooks sign different input, so they need their own verifier. See two kinds of webhooks.

import express from 'express';
import { createHmac, timingSafeEqual } from 'crypto';

function verifyWebhook(rawBody: string, signature: string | undefined, secret: string): boolean {
  if (!signature) return false;

  const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
  const signatureBuffer = Buffer.from(signature, 'hex');
  const expectedBuffer = Buffer.from(expected, 'hex');

  if (signatureBuffer.length !== expectedBuffer.length) {
    return false;
  }

  return timingSafeEqual(signatureBuffer, expectedBuffer);
}

const app = express();

// In your handler
app.post('/webhooks/conto', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.header('x-conto-signature');
  const rawBody = req.body.toString('utf8');

  if (!verifyWebhook(rawBody, signature, process.env.CONTO_WEBHOOK_SECRET!)) {
    return res.status(401).send('Invalid signature');
  }

  const { event, data } = JSON.parse(rawBody);

  switch (event) {
    case 'payment.confirmed':
      console.log('Payment confirmed:', data.transactionHash);
      break;
    case 'payment.denied':
      console.log('Payment denied:', data.reasons);
      break;
  }

  res.status(200).send('OK');
});

The same rule applies in other frameworks: verify the exact raw request body before you parse it.

Retry behavior

Each delivery gets up to 3 attempts in total. An attempt fails if your endpoint returns a non-2xx status or doesn’t respond within 10 seconds. Conto retries only failures that can succeed on replay: a network error, a timeout, or an HTTP 408, 429, or 5xx response. Any other status (for example 400, 401, or 404) ends the delivery after that attempt.

Attempt	Timing
1	Immediate
2	About 1 second after attempt 1 fails
3	About 2 seconds after attempt 2 fails

Every attempt carries the same X-Conto-Delivery-Id (also deliveryId in the body). Use it to dedupe a delivery you already processed.

Agent callback URLs

An agent can also have its own callbackUrl, set with POST /api/agents and changed or cleared with PATCH /api/agents/{id}. Events for that agent then go to both the organization URL and the callback URL, with the same payload format and signature headers. Policy and governance events go only to the organization webhook. Agent callbacks are signed with the same organization signing secret as the organization webhook. The first time you configure a callback URL (or an organization webhook URL), the response includes webhookSecret once. Store it to verify the X-Conto-Signature on callback deliveries. If you did not capture it, rotate it from Settings > Event Delivery and update your receiver. Authenticated agent reads return webhookConfigured and the configured callbackUrl. Responses replace query and fragment values with REDACTED because callback URLs commonly carry credentials. Send the full URL again when rotating those values.

Settlement mode in payment events

The payment.executed payload includes settlementMode: test for simulated execution or live for an onchain transfer, including testnet. Simulated events omit transactionHash, so use the payment ID to read status. A payment.confirmed event represents onchain confirmation and reports live. Do not treat a simulated execution event as proof that funds moved.

Get started

Integrate

Payments

Conto Commerce

Spending controls

Operate

Conto Pay

Two kinds of webhooks

Test a local handler

Setup

Event types

Governance events for SIEM and GRC

Payload format

Headers

Body

Verifying signatures

Retry behavior

Agent callback URLs

Settlement mode in payment events

​Two kinds of webhooks

​Test a local handler

​Setup

​Event types

​Governance events for SIEM and GRC

​Payload format

​Headers

​Body

​Verifying signatures

​Retry behavior

​Agent callback URLs

​Settlement mode in payment events

Two kinds of webhooks

Test a local handler

Setup

Event types

Governance events for SIEM and GRC

Payload format

Headers

Body

Verifying signatures

Retry behavior

Agent callback URLs

Settlement mode in payment events