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

# Configure Tavryn Webhooks for Real-Time Agent Events

> Set up outbound webhooks for real-time Tavryn events in Slack, Discord, or a custom endpoint — plus how Circle webhooks keep payment status in sync.

Tavryn's webhook system connects your procurement agent's autonomous activity to the tools your team already uses. Whenever Tavryn detects waste, starts a negotiation, proposes a deal, requires your approval, or settles a payment, it fires an outbound webhook to the URL you configure. Separately, Circle's inbound webhook integration keeps on-chain transaction status synchronized in real time so your dashboard always reflects the true state of every payment.

## Configuring Your Outbound Webhook

**1. Open Settings**

Navigate to your business **Settings** page in the Tavryn dashboard.

**2. Enter your webhook URL**

Find the **Notification Webhook** field and paste your Slack Incoming Webhook URL, Discord webhook URL, or any custom HTTPS endpoint.

**3. Test the connection**

Click **Test Webhook**. Tavryn sends a sample payload to your endpoint. Confirm you receive it before saving.

**4. Save**

Click **Save Settings**. All future events for this business will POST to the configured URL.

You can also update your webhook URL programmatically via the API:

```bash theme={null}
PUT /api/business/{businessId}/settings
Content-Type: application/json

{
  "webhook_url": "https://hooks.slack.com/services/T.../B.../..."
}
```

## Events That Trigger Webhooks

Tavryn fires a webhook notification for each of the following agent events:

| Event | Category | Description |
| - | - | - |
| **Waste detected** | `renewal` | Tavryn identifies idle seats or declining usage within the 45-day renewal window |
| **Negotiation started** | `negotiation` | The autonomous agent begins multi-round concession negotiation with a vendor |
| **Deal proposed** | `negotiation` | The agent reaches a candidate deal and submits it to the adversarial reviewer |
| **Approval required** | `policy` | The deal exceeds auto-approval thresholds — a 1-tap HMAC approval link is issued to supervisors |
| **Payment settled** | `treasury` | USDC is released from escrow to the vendor on-chain after verified delivery |
| **Low treasury balance** | `treasury` | Your USDC balance drops below 100 USDC |
| **Audit alert** | `audit` | The adversarial reviewer issues a `CHALLENGE` or `REJECT` verdict requiring human review |

## Outbound Webhook Payload Structure

Every outbound webhook is a `POST` request with a `Content-Type: application/json` body. The exact payload shape adapts to the platform (Slack, Discord, or generic HTTP) detected from the URL:

> [tab] Generic HTTP
>
> ```json theme={null}
> {
>   "title": "Deal Approved: Slack renewal at $18,200/yr",
>   "message": "Tavryn negotiated a 28% reduction from $25,200. Escrow funded. Awaiting vendor delivery confirmation.",
>   "content": "**Deal Approved: Slack renewal at $18,200/yr**\nTavryn negotiated a 28% reduction from $25,200. Escrow funded. Awaiting vendor delivery confirmation.\nView: https://app.tavryn.com/dashboard",
>   "text": "*Deal Approved: Slack renewal at $18,200/yr*\nTavryn negotiated a 28% reduction from $25,200."
> }
> ```

> [tab] Slack
>
> ```json theme={null}
> {
>   "text": "*Deal Approved: Slack renewal at $18,200/yr*\nTavryn negotiated a 28% reduction from $25,200. Escrow funded. Awaiting vendor delivery confirmation.\nView: https://app.tavryn.com/dashboard"
> }
> ```

> [tab] Discord
>
> ```json theme={null}
> {
>   "content": "**Deal Approved: Slack renewal at $18,200/yr**\nTavryn negotiated a 28% reduction from $25,200. Escrow funded. Awaiting vendor delivery confirmation.\nView: https://app.tavryn.com/dashboard"
> }
> ```

Webhooks include a link to the relevant page in the Tavryn dashboard whenever a direct action is available (such as an approval link or transaction view).

## Webhook Delivery & Timeouts

Tavryn dispatches outbound webhooks asynchronously so that a slow or unavailable external endpoint never blocks the autonomous agent loop. If your endpoint returns a non-2xx response or times out, Tavryn logs a warning but continues normal operation. Retry logic is not currently applied — ensure your endpoint is reliably available.

## Circle Inbound Webhooks

Tavryn also receives inbound webhooks from Circle to keep on-chain transaction status synchronized in your dashboard. These are sent by Circle whenever the state of a developer-controlled wallet transaction changes.

**Endpoint:** `POST /api/webhooks/circle`

### Subscription Confirmation Handshake

When you register this endpoint with Circle, Circle sends a `SubscriptionConfirmation` message. Tavryn automatically responds by GETting the `SubscribeURL` to complete the handshake — no manual action is required on your part.

```json theme={null}
{
  "Type": "SubscriptionConfirmation",
  "SubscribeURL": "https://sns.us-east-1.amazonaws.com/..."
}
```

### Transaction Lifecycle Events

Circle fires webhooks for each state transition in a transaction's lifecycle. Tavryn maps these states to the payment status shown in your dashboard:

| Circle State | Dashboard Status | Meaning |
| - | - | - |
| `CONFIRMED` | `funded` (if previously pending) | Transaction confirmed on-chain; escrow is funded |
| `COMPLETE` | `completed` | Final settlement confirmed |
| `SUCCESS` | `funded` / `completed` | Alias for confirmed/complete depending on prior state |
| `FAILED` | `failed` | Transaction failed on-chain |
| `CANCELLED` | `failed` | Transaction was cancelled |
| `REJECTED` | `failed` | Transaction was rejected |

**Example Circle transaction webhook payload:**

```json theme={null}
{
  "notificationType": "transactions.outbound",
  "transaction": {
    "id": "circle-tx-uuid",
    "txHash": "0xabc123...",
    "state": "COMPLETE"
  }
}
```

## Supported Platforms

Tavryn auto-detects the webhook platform from the URL and formats the payload accordingly:

> [card] Slack
>
> Any URL containing `slack.com` — formats payload as `{ "text": "..." }` using Slack's Incoming Webhook schema.

> [card] Discord
>
> Any URL containing `discord.com` — formats payload as `{ "content": "..." }` using Discord's webhook schema.

> [card] Custom HTTP
>
> Any other HTTPS endpoint — sends the full payload including `title`, `message`, `content`, and `text` fields for maximum compatibility.


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