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 aSubscriptionConfirmation 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)
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 structurestring
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
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:- Primary match — Tavryn queries for a transaction where
circle_tx_idequals thetransaction.idfrom the event payload. - Fallback match — If no match is found by
circle_tx_id, Tavryn queries bytx_hashusing thetransaction.txHashfield.
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.Audit Logging
When Tavryn successfully matches and processes a Circle event, it writes an entry to the immutable agent audit log with actioncircle_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.