Skip to main content
The Circle webhook endpoint is a server-to-server callback receiver that Tavryn exposes to Circle’s Developer-Controlled Wallets platform. Circle calls this URL automatically whenever a transaction changes state — confirmed on-chain, completed, failed, or cancelled. Tavryn matches each incoming event to an internal transaction record and advances its status accordingly, keeping your payment records in sync with the Arc network without any polling. You register this endpoint URL in your Circle project settings; you do not call it directly.
This endpoint is designed for Circle’s servers to call Tavryn, not for you to call manually. It handles both the initial subscription confirmation handshake and ongoing transaction lifecycle events. Sending ad-hoc requests to this endpoint from your own code will have no meaningful effect on payment state.

POST /api/webhooks/circle

Receives all Circle Developer-Controlled Wallets webhook events. The endpoint handles two distinct event types: the one-time subscription confirmation challenge and recurring transaction state notifications. Authentication Circle signs its webhook deliveries at the platform level. Tavryn trusts events received at this endpoint. Do not expose this URL publicly in client-side code.

Subscription Confirmation Handshake

When you register this endpoint URL in Circle’s dashboard, Circle immediately sends a SubscriptionConfirmation challenge. Tavryn automatically responds by fetching the SubscribeURL provided in the payload, completing the handshake, and returning a confirmation acknowledgement. Confirmation payload shape (sent by Circle)
Tavryn’s response
Tavryn also accepts notificationType: "subscription.confirmation" and subscribeUrl (camelCase) as alternative field names in case Circle changes its payload format.

Transaction Notification Events

After the subscription is confirmed, Circle sends a notification each time a tracked transaction advances through its lifecycle. Tavryn extracts the transaction identifiers, matches the event to an internal record, and updates the status. Event payload structure
string
Describes the event type. Common values include "transaction.confirmed", "transaction.complete", and "transaction.failed". Tavryn also accepts type and NotificationType as fallback field names.
object
Example notification payload

State Mapping

Tavryn maps Circle’s transaction state strings to its own internal status values:
The CONFIRMED state advances a pending transaction to funded (Circle confirmed, awaiting Arc finality) rather than directly to completed. A second event with COMPLETE or SUCCESS then moves it to completed. This two-step progression ensures your transaction records accurately reflect whether Arc block finality has been reached.

Event Matching Logic

Tavryn uses a two-pass lookup to match an incoming Circle event to an internal transaction record:
  1. Primary match — Tavryn queries for a transaction where circle_tx_id equals the transaction.id from the event payload.
  2. Fallback match — If no match is found by circle_tx_id, Tavryn queries by tx_hash using the transaction.txHash field.
If neither lookup finds a matching record, Tavryn still returns HTTP 200 with matched: false — unrecognized events are acknowledged to prevent Circle from retrying indefinitely.

Response Fields

boolean
Always true when the event was successfully parsed, regardless of whether a matching transaction was found.
string
The event type extracted from the incoming payload, echoed back for debugging.
boolean
true if Tavryn found an internal transaction record corresponding to this event. false for subscription confirmations and unrecognized transaction IDs.
string | null
Tavryn’s internal UUID for the matched transaction. null if no match was found.
Example response — matched transaction
Example response — unmatched event
Error responses

Audit Logging

When Tavryn successfully matches and processes a Circle event, it writes an entry to the immutable agent audit log with action circle_webhook_synced. The log entry includes the notificationType, circleTxId, txHash, state, the previous transaction status, and the new status. You can review these entries in the Tavryn dashboard under Agent Activity.
Do not use this endpoint as a general-purpose status notification receiver for your own events. It expects Circle’s exact payload structure and will silently ignore payloads that don’t match the expected shape. Use the Business Settings API to configure a separate webhook_url if you want Tavryn to push procurement events to your own systems.