> ## Documentation Index
> Fetch the complete documentation index at: https://tavryn.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks API: Circle Transaction Event Listener

> Circle webhook receiver for transaction lifecycle events. Tavryn syncs USDC payment status automatically — register this URL in your Circle project.

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.

> [!NOTE]
>
> 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)**

```json theme={null}
{
  "Type": "SubscriptionConfirmation",
  "SubscribeURL": "https://circle.com/confirm?token=abc123..."
}
```

**Tavryn's response**

```json theme={null}
{
  "confirmed": true,
  "message": "Subscription confirmed"
}
```

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**

**notificationType** `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.

**transaction** `object`

**transaction fields**

**id** `string`

Circle's UUID for this transaction (`circle_tx_id` in Tavryn's database).

**txHash** `string`

The on-chain transaction hash on the Arc network. Also accepted as `transactionHash`.

**state** `string`

Circle's reported transaction state. Tavryn maps these to internal statuses — see the table below.

**Example notification payload**

```json theme={null}
{
  "notificationType": "transaction.confirmed",
  "transaction": {
    "id": "9f8e7d6c-5b4a-3c2d-1e0f-a9b8c7d6e5f4",
    "txHash": "0x4a3b2c1d9e8f7a6b5c4d3e2f1a0b9c8d...",
    "state": "CONFIRMED"
  }
}
```

***

## State Mapping

Tavryn maps Circle's transaction state strings to its own internal status values:

| Circle `state` | Tavryn transition |
| - | - |
| `CONFIRMED` | `pending` → `funded`; any other status → `completed` |
| `COMPLETE` | Same as `CONFIRMED` |
| `SUCCESS` | Same as `CONFIRMED` |
| `FAILED` | Any status → `failed` |
| `CANCELLED` | Any status → `failed` |
| `REJECTED` | Any status → `failed` |

> [!NOTE]
>
> 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

**received** `boolean`

Always `true` when the event was successfully parsed, regardless of whether a matching transaction was found.

**notificationType** `string`

The event type extracted from the incoming payload, echoed back for debugging.

**matched** `boolean`

`true` if Tavryn found an internal transaction record corresponding to this event. `false` for subscription confirmations and unrecognized transaction IDs.

**transactionId** `string | null`

Tavryn's internal UUID for the matched transaction. `null` if no match was found.

**Example response — matched transaction**

```json theme={null}
{
  "received": true,
  "notificationType": "transaction.confirmed",
  "matched": true,
  "transactionId": "c9a1f820-1234-4d56-a789-bc3d0e001f22"
}
```

**Example response — unmatched event**

```json theme={null}
{
  "received": true,
  "notificationType": "transaction.confirmed",
  "matched": false,
  "transactionId": null
}
```

**Error responses**

| Status | Condition |
| - | - |
| `400` | Payload is not valid JSON |
| `500` | Internal error processing the webhook event |

***

## 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**.

> [!WARNING]
>
> 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](https://tavryn.mintlify.site/api-reference/business-settings.md) to configure a separate `webhook_url` if you want Tavryn to push procurement events to your own systems.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.