Skip to main content

Webhooks

Conto sends HTTP POST requests to your configured URL when payments progress, an A2A payment request is created, a service spend record is written, an agent is frozen or unfrozen, a policy changes, or an approval is decided.

Setup

  1. Go to Settings > Event Delivery in the dashboard
  2. Enter your HTTPS endpoint URL
  3. Copy the generated signing secret, you’ll need this to verify payloads
Webhook URLs must use HTTPS. HTTP, loopback hosts, and private IP ranges are blocked for security (SSRF protection).

Event Types

Governance events for SIEM/GRC

policy.*, approval.*, and governance.approval.decided stream policy and approval-decision activity to your webhook so you can build 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, agentId, amount, and decision.
  • 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

Body

Verifying Signatures

Every payload is signed with your webhook secret using HMAC-SHA256. Verify signatures to confirm the request came from Conto. These event webhooks sign the raw request body only. Conto’s approval notification-channel webhooks use a different signed input, timestamp.rawBody, under the same X-Conto-Signature header. Match your verifier to the webhook you are receiving.
The same rule applies in other frameworks: verify the exact raw request body before you parse it.

Retry Behavior

Failed deliveries are retried up to 3 times with exponential backoff: A delivery is considered failed if your endpoint returns a non-2xx status code or doesn’t respond within 10 seconds.

Agent Callback URLs

In addition to organization-level webhooks, individual agents can have a callbackUrl set with POST /api/agents and changed or cleared with PATCH /api/agents/{id}. When set, webhooks are delivered to both the organization URL and the agent’s callback URL. 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 so you can verify the target. Query and fragment values are replaced with REDACTED in responses because callback URLs commonly carry credentials. Send the full URL again when rotating those values.

Delivery Targets

Both targets receive the same payload format and signature headers.