Agentic Webhooks

Agentic payments adds exactly one webhook event: scheduled_payment.failed. Everything else rides signals you already consume. For delivery mechanics — Ed25519 signature verification, targets, retries — see the main Webhook Integration guide. This page covers the agentic-specific payloads and how to react to them.

Why only failures get a new event

A scheduled payment is the only asynchronous agentic actor: the platform fires it later, unattended. Every other agentic operation is synchronous — the caller holds the response.

A scheduled payment that succeeds emits the standard wallet.transaction.created through the shared money path, indistinguishable from any other send. Correlate it via wallet_transaction_id on the executed scheduled payment (GET /scheduled-payments).
A scheduled payment that fails emits scheduled_payment.failed with a machine-readable failure_code.

`scheduled_payment.failed`

Fires on every fire-path failure: mandate denial, no covering mandate, agent revoked, wallet no longer recognizing the signer, chain-family mismatch, unsupported network, invalid amount, and money-path send errors. It does not fire for successful payments or for rows already in a terminal state.

Payload (`data.object`)

Field	Always present	Notes
`scheduled_payment_id`	✅	the failed schedule row
`signer_id`	✅	the signer the row fires under
`wallet_id`	✅	the funding wallet
`address`	✅	the crypto address the row pays (for auto-account payments, the deposit address)
`amount`	✅	decimal string, destination asset
`asset`	✅	e.g. `USDC`
`network_id`	✅	e.g. `base-sepolia`
`scheduled_at`	✅	unix seconds
`failure_code`	✅	stable machine-readable code — react on this
`failure_reason`	✅	human-readable detail; wording may change, never parse it
`payment_agent_id`	when applicable	the payment agent whose signer this is; omitted for non-agent signers
`recipient_id`	when applicable	present when the schedule targets a recipient’s destination
`destination_id`	when applicable	the real destination — bank for an offramp, crypto otherwise

Optional fields are omitted when not applicable — treat absence as “not applicable”, never as an empty string.

`failure_code` reference

Code	Meaning	Typical reaction
`mandate_denied`	the mandate gate denied it — cap exhausted, target/asset/network mismatch, or validity window	adjust expectations or sign an additional mandate
`no_mandate`	no active mandate covered the payment at fire time	create + approve a covering mandate
`agent_revoked`	the payment agent was revoked	expected if you revoked it; otherwise create a new agent
`wallet_not_recognized`	the signer is no longer recognized on the funding wallet	re-attach the agent’s signer to the wallet’s signer group
`wallet_family_mismatch`	the wallet’s chain family can’t send on the payment’s network	schedule from a compatible wallet
`unsupported_network`	the payment’s network is not supported	fix the schedule
`invalid_amount`	the amount is unparseable or non-positive	fix the schedule
`send_error`	pre-checks passed but the send failed (provider/transport)	often transient — re-schedule to retry
`internal_error`	platform-side error during the fire	typically transient; retry or contact support

failure_code is the contract; failure_reason is diagnostic color for humans.

Delivery & idempotency

The event is emitted in the same transaction as the payment’s flip to failed — exactly one event exists per status change. Delivery, as with all Dakota webhooks, is at-least-once: dedupe on the event id. Global webhook targets receive the event automatically; scoped targets subscribe to it by event type like any other. It also appears in the GET /events stream, so a poll-based consumer needs no webhook endpoint at all.

A practical failure handler

on scheduled_payment.failed:
  if seen(event.id): ack and stop          # at-least-once delivery
  switch failure_code:
    case send_error, internal_error:       # transient
      re-schedule the payment (new POST /scheduled-payments)
    case no_mandate, mandate_denied:       # authority problem
      surface to the customer: review mandates, sign more headroom
    case wallet_not_recognized, wallet_family_mismatch, agent_revoked:
      surface to the operator: wiring problem, fix the binding
    default:                               # unsupported_network, invalid_amount
      fix the schedule data before retrying

The Account Insights report also picks failures up (payment_failures_clustered groups repeats by payee and shared reason) — useful as the human-facing view over the same signal.

Playground

Documentation

Agentic Payments

Authentication

Developer Tools

Agentic Webhooks

Why only failures get a new event

`scheduled_payment.failed`

Payload (`data.object`)

`failure_code` reference

Delivery & idempotency

A practical failure handler

​Why only failures get a new event

​scheduled_payment.failed

​Payload (data.object)

​failure_code reference

​Delivery & idempotency

​A practical failure handler

Why only failures get a new event

`scheduled_payment.failed`

Payload (`data.object`)

`failure_code` reference

Delivery & idempotency

A practical failure handler