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
- Go to Settings > Event Delivery in the dashboard
- Enter your HTTPS endpoint URL
- Copy the generated signing secret, you’ll need this to verify payloads
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) carrypolicyId,name, andpolicyType, never the underlying rule values.policy.createdalso includesscope,priority, andrulesCount;policy.updatedincludesisActive. - Approval events (
approval.approved/approval.denied) carryapprovalRequestId,paymentRequestId,agentId,amount, anddecision. governance.approval.decided(separation-of-duties decisions on sensitive changes) carriesgovernanceApprovalRequestId,action,resource,resourceId, anddecision.
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.
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 acallbackUrl 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.