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, or an agent is frozen or unfrozen.

Setup

  1. Go to Settings > Webhooks 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, localhost, and private IP ranges are blocked for security (SSRF protection).

Event Types

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.
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 during creation. When set, webhooks are delivered to both the organization URL and the agent’s callback URL.

Delivery Targets

Both targets receive the same payload format and signature headers.